|
|
The correct response to such a statement is:
"Just because your mother slept with her brother doesn't mean the rest of us will agree it's a good idea."
Panic, Chaos, Destruction. My work here is done.
Drink. Get drunk. Fall over - P O'H
OK, I will win to day or my name isn't Ethel Crudacre! - DD Ethel Crudacre
I cannot live by bread alone. Bacon and ketchup are needed as well. - Trollslayer
Have a bit more patience with newbies. Of course some of them act dumb - they're often *students*, for heaven's sake - Terry Pratchett
|
|
|
|
|
(c++ centric answer)
Stupid/Verbose/Out of sync comments are worse than no comments.
All functions and parameter names should be self-descriptive; use proper user defined types instead of POD (if you have a student ID, let the type be a StudentID instead of a int)
All functions should be as simple as possible; they should do 1 thing only; methods should be const if they do not modify the data,
Special cases should be fixed by proper code design than by adding a comment in the code (i.e. parameter can be NULL or not, or sometimes ... ), if a method cannot receive a NULL pointer, just change the type to a reference; let the client of that function clean up its own code to not have a null pointer.
When there are good coding practice, comments are not "that" necessary, needed in some instances, but not always necessary.
Nihil obstat
|
|
|
|
|
Maximilien wrote: Stupid/Verbose/Out of sync comments are worse than no comments.
This is similar to the many many dev. arguments where the adage is something done badly is bad - well, of course bad comments are bad - so is bad code! Ill maintained comments can be bad - so can ill maintained code.
CODE and COMMENTS are all part of the code base - i don't think they should be thought of as something separate and they should be included in code reviews.
A comment that says
// Update the Customer
for a method
public void UpdateCustomer()
is obviously a waste of time, and is often the sort of comment that people who don't think they should be made to comment code put in - in a sort of "see, i told you commenting was a waste of time!"
But what does UpdateCustomer() do? Does it update the local customer object, persist it to the database, change some properties? Evidently UpdateCustomer is an insufficient comment and an insufficient method name - but ...
I think in a sense there are two types of comment...
1. Code comments. This is the sort of comment you are talking about, I think.
2. Business comments - this explains to the programmer the business of the function or code block.
A method name of
public StockItem FindTheStockItemWithTheEarliestSellByDateThatIsEitherOfTheTypePassedOrOneOfTheGenericTypesSimilarToThatTypeThatIsAcceptableByTheCustomer(StockType stockType, Customer customer, Date dateToCheck)
{
}
Is simply less legible than the equivalent
public StockItem FindStock((StockType stockType, Customer customer, Date dateToCheck)
{
}
|
|
|
|
|
Maximilien wrote: Stupid/Verbose/Out of sync comments are worse than no comments.
However that is also a good indication that code reviews are not occurring or at least they are not being done correctly.
|
|
|
|
|
|
... and that's when the fight started.
Software Zen: delete this;
|
|
|
|
|
In general I agree with the goal of having self-documenting code. However, that's not always possible or feasible. Judicious, and appropriate commenting is as important as well architected and well implemented code. The comments should inform me why you're doing what you're doing, not what you're doing. For that, I can read the code. If it's not immediately obvious from the code why something is being done, then a comment, as short as possible, is necessary.
Finally, when the code is updated, please, please update the comments. I've seen too much code where the comments no longer apply.
If your actions inspire others to dream more, learn more, do more and become more, you are a leader.-John Q. Adams You must accept one of two basic premises: Either we are alone in the universe, or we are not alone in the universe. And either way, the implications are staggering.-Wernher von Braun Only two things are infinite, the universe and human stupidity, and I'm not sure about the former.-Albert Einstein
|
|
|
|
|
ahmed zahmed wrote: ...is as important as well architected and well implemented code.
Yes but that there is probably the reason comments are needed because after all how many developers do you come across who are willing to say that they are creating code that is poorly architected and poorly implemented?
Excluding some (but far from all) beginning programmers I have very seldom come across anyone that felt that they were producing poor code. So one might then conclude that no one should comment code because everyone is producing great code.
And then there is also the implicit problem that presumes that that good is the only possible solution that many people would come up with. Thus everyone should understant it in the first place because it is the only possible solution. Rather than one of ten or even one of 100.
|
|
|
|
|
Nothing you've said, while true, negates what I've said. In fact, your statements support what I've said. Note that I said good comments are as important as good code, that goes at least doubly-so for "bad" code. Again, explain why you're doing what you're doing, not what.
And yes, I've worked with some people who've admitted to producing "bad" code (myself included). Usually it was only meant to be a short-lived workaround, demo, or prototype, but got left in the product by time crunch or management decision.
And, btw, the only viable, real solutions are the ones I come up with!
If your actions inspire others to dream more, learn more, do more and become more, you are a leader.-John Q. Adams You must accept one of two basic premises: Either we are alone in the universe, or we are not alone in the universe. And either way, the implications are staggering.-Wernher von Braun Only two things are infinite, the universe and human stupidity, and I'm not sure about the former.-Albert Einstein
|
|
|
|
|
_Maxxx_ wrote: because it is self documenting, all methods are small and have single
functionality
All of those are opinions.
_Maxxx_ wrote: and any business documentation should be provided by the specification and not
the code.
If in fact the business specification is a technical specification and well done it is possible that is true.
But since most business specifications are not technical specifications the first part of the assertion becomes questionable.
And since many are not kept completely up to date throughout a project the second part assertion is also questionable. Not to mention of course that the second part is...again...an opinion.
|
|
|
|
|
opinions, there're like assholes: everyone's got one and they're usually full of shit!
If your actions inspire others to dream more, learn more, do more and become more, you are a leader.-John Q. Adams You must accept one of two basic premises: Either we are alone in the universe, or we are not alone in the universe. And either way, the implications are staggering.-Wernher von Braun Only two things are infinite, the universe and human stupidity, and I'm not sure about the former.-Albert Einstein
|
|
|
|
|
I see nothing wrong with this approach. I work in scientific computing and rarely see commented code. I do not comment my own code. I used to work with Microsoft Dynamics, nothing was commented. IIRC when working with the Source Engine or UT2004 in GD none of the source code had comments. Any comments I have ever seen have simply reflected what was obvious from the function name. If you can't read code how are you doing your job? Naming convention is far more important and far less intrusive. Good documentation in my opinion is far more helpful. If you want to comment use hyperlinks to electronic documentation.
|
|
|
|
|
Xittenn wrote: Good documentation in my opinion is far more helpful. Do you work in a shop where documentation is manually generated?
/ravi
|
|
|
|
|
Your question is a little vague given my examples. When you say shop I am assuming industrial and related to my Dynamics comment. We did generate our 'documentation' both manually and automatically. Stepping away from the industrial concept and into scientific research, all my documentation is generated manually(I would imagine the same would hold in a game studio.) In science it's about solvers and these tend to be complex entities that are not readily documented by any automated techniques that I am aware of(do enlighten.) Again your question is a little vague(from my perspective,) I'm not entirely sure what you were expecting as a response.
|
|
|
|
|
Xittenn wrote: When you say shop I am assuming industrial shop == software development team
Xittenn wrote: all my documentation is generated manually(I would imagine the same would hold in a game studio.) Bad assumption.
All our API documentation is generated automatically. Just like the .NET, Java and Android APIs.
/ravi
|
|
|
|
|
I see you have a very firm stance on your coding techniques and best practices, and I get the strong feeling that you do not appreciate the alternative. My original post was not intended to dissuade, but I really don't like some of the overly eager approaches being taken by certain 'shops' and where it is in turn expected that my 'shop' hold these same values. If I were to come into a situation where inlined comments allowed an automation process to produce clear documentation--and this was the best solution--I would post this as well. To date I have not! And again, not too sound as though this is standard across the board, but of all the code I've worked with the standards seemed pretty much the same.
I'm kind of bothered how the first quote you made was abbreviated out of its original context. Not every 'shop'--as you put it--is an agile code tank, and that was my point.
|
|
|
|
|
Xittenn wrote: Not every 'shop'--as you put it--is an agile code tank Agree wholeheartedly! But note that automated generation of API documentation is unrelated to using agile development process. Not sure why you connected the two.
The nice thing about using automated API documentation generation tools like JavaDoc[^] and Sandcastle[^] and NDoc[^] is that they allowa a single source of comments (i.e. in the code) to be maintained. This makes it easy to ensure that the generated docs are up-to-date and reduces the risk of introducing miscommunication between the author of the comments and another team that may be tasked with producing the documentation.
I didn't mean to imply that end-user documentation (user's guides) can be created without the assistance of a technical writer.
/ravi
|
|
|
|
|
I connected the two based on high correlation!
Ravi Bhavnani wrote: The nice thing about using automated API documentation generation tools like JavaDoc[^] and Sandcastle[^] and NDoc[^] is that they allowa a single source of comments (i.e. in the code) to be maintained. This makes it easy to ensure that the generated docs are up-to-date and reduces the risk of introducing miscommunication between the author of the comments and another team that may be tasked with producing the documentation.
And if that's appropriate for your project by all means use it.
I don't believe that the above holds as fact for all projects. Automation is not as simply implemented as you make it sound, and this is why a good number of teams do not implement such a strategy. For starters, in my 'shop' documents are created before code not the other way around. Versioning comments in combination with code becomes a chore when the code should be following the documentation. And back to my original statement, if all that is being commented and documented is the formatting of the code, the coder should be able to read the code on its own or else it isn't very well organized to begin with.
My argument is not that there is never a circumstance where comments are not required. My argument is simply if you do not require them there is no obligation by some imaginary standard that others have created.
|
|
|
|
|
In-line comments are debatable: it depends upon how "self-documenting" your names and language are.
Pre-ambles are a must, especially when your IDE will give you intellisense when they're present.
Regards,
Mark Hurd, B.Sc.(Ma.) (Hons.)
|
|
|
|
|
Comments are great when done well. Unfortunately this is rarely the case...
The following is a real world example...
product.Save(); Another one:
int i = 0; Just call the friggin variable 'index' and drop the comment!
this.DoSomething(); Who the hell is QQ and what mail did he send?
It's also nice to find change logs in code, comments just for the sake of commenting, comments that describe code that isn't there anymore, a piece of comment that's littered all over your codebase...
Comments are lines of code that should be maintained like any other line of code.
I hate it when it's perfectly clear to me what a piece of code does, but someone thought it would be nice to still comment it. Now I have to read/adjust the code AND the comment...
Comments get out of date, comments lie, comments can be as obscured and unclear as the code itself and comments can be an excuse to write bad code (the code is commented, so it's clear what the code does, right?)... In my opinion comments are a necessary evil at best. The code should speak for itself. Code does not lie and is never outdated. Now it's up to the programmer to make it as clear and readable as possible (unfortunately this is not easy and just straight impossible for some programmers...). But then again, writing good comments is not easy either.
I always imagine a writer writing a book. Would he have to comment his paragraphs?
// What I mean to say in the following section is that Frodo takes his ring to Mount Doom to destroy it, but is attacked by the creature we know as Gollum.
(actual text) jkfhadj.kbvadulvkb;jlbn av,lnvaduk aa;vn ;ub jb kgbfleukg vbvs
dfgg afgh;a jafhuhg jdbakjbfjgdfgbukfha afdgfhfdh g fdgfadfgafg fgafdgarerthgaer9df/d.kj fgjdakh
adfg f8oyfagh ahg hgafoihlawr;ahbnfbjn afad;jkh gfnadjkh89fadyg
Unfortunately that is what a lot of code really looks like...
It's an OO world.
public class Naerling : Lazy<Person>{
public void DoWork(){ throw new NotImplementedException(); }
}
|
|
|
|
|
Code can and should to be self documenting, thus the comments explaining what it does are both unnecessary and harmful. The problem is that claiming that does not automatically make the code self documenting. However, comments explaining why the code does what it does are absolutely necessary. The code itself is not the best place for such comments, they are easier to use when placed into a separate document. Thus, if nothing but "code is self documenting" is said about comments, it is likely the coder does not understand the job. The "provided by specification" part makes me think that is the fact here since specification cannot answer the why. The big WHY is being understood while coding.
|
|
|
|
|
77465 wrote: The code itself is not the best place for such comments, they are easier to use when placed into a separate document. Do you really believe this?
/ravi
|
|
|
|
|
There are a number of interesting aspects to the "comment / don't comment" debate. Let's dispose of the easy ones first:
1. Trivial comments. Lord, let me never again see:
i++; // Increment I by one.
...in a subordinate's code.
2. Comments about technique or mechanics. If your code comments are about technology rather than "business logic," they're probably unnecessary. Yes, it's interesting beyond words that you chose a Shell-Metzner sort over the easier to use Quicksort, but "beyond words" is probably where it belongs. Matters of programming technique are easily looked up online or in reference books.
3. Drift, Type 1. As with external documentation, comments can drift away from the code to which they're attached. That doesn't mean the code shouldn't be commented; it merely means that the comments should be maintained along with the code -- and to fail to do so is to fail as a programmer.
Now for the not-so-easy ones:
4. Drift, Type 2. If there has been a significant alteration in the application, such that the earlier "business logic" no longer applies, it will probably -- let's hope, anyway -- have been captured in a revision of a requirements specification. That, of course, will compel significant alterations to the code...but the new "business logic," as instantiated in the code, should still be annotated in comments unless that logic is so trivial as to require no comment whatsoever (e.g., profit = price - aggregate cost of production).
5. Posterity. You, the developer, are prone to think only of your own needs and desires while you're in the process of developing your application. But it's even money or better that you won't be the last programmer to work on that program -- and it's six-five and pick 'em that your successor:
- Won't be nearly as conversant with the application's "business logic" as you've come to be;
- Won't agree with your technique or your coding style in all particulars;
- Will be under serious deadline pressure and could use all the help he can get!
Actually, it can be even worse than that: the guy who picks up your program and tries to fix or modify it could well be very, very junior, and thus exposed to all sorts of hazards you, the senior developer, are (relatively) well protected from. Uncommented code can be a nightmare for such a maintenance programmer, especially as the most junior sorts typically get the dirtiest jobs and are utterly unprepared by their "educations" for the challenges of practical software engineering. There's plenty of room in our trade for human kindness to your unnamed, unseen inheritors.
6. Polymorphism has its own challenges. If you employ an oblect-oriented language that's liberal about polymorphism, you're likely to write methods that have the same name but do appreciably different things. These divergences should be commented, and carefully. Likewise, we tend to be blase about the reuse of names for variables at different levels of scope. This isn't good practice, but most of us fall prey to it. If you're going to do so, then accept the obligation to comment those variations, as well, with appropriate mention of the scoping differences.
7. Low-level languages. Don't even dream about writing C, assembler, or (God help us) microcode without comments!
Just now, this subject is of unusual importance to me, as I'm struggling to convert a 250,000 line C# (gag, retch, barf) program from one point of application to another, vaguely related one for which it was never intended -- no, I wasn't given any choice in the matter -- and the damned thing was written by a committee of mutually hostile developers, not one of whom is still available to support it, and it doesn't have a single line of commentary in it.
Please, please: Don't do this to others. God will have harsh words for you at the Bar of Judgment.
(This message is programming you in ways you cannot detect. Be afraid.)
|
|
|
|
|
Been there, done that, have tooo many t-shirts.
I used to work with S/370 Assembler programmers who would tell me it was a waste of time to comment the code since the instruction tells you what it is doing. I made the same argument that it doesn't tell you why.
If they weren't telling me not to comment, they were griping the S/370 had too many instructions. As far as they were concerned, you only needed Load, Store, Add, and Branch. I suppose years later they were in nirvana when RISC was announced.
Of course they didn't like going through my code since I used (shudder) MACROS and (horrors) symbolic register assignments instead of hardcoded numbers. That last part really blew there minds because I'd have code that read
BALR RTN, PRINT
instead of
BALR 8, PRINT
Psychosis at 10
Film at 11
Those who do not remember the past, are doomed to repeat it.
Those who do not remember the past, cannot build upon it.
|
|
|
|
|