|
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.
|
|
|
|
|
My God. There are really programmers who think it's okay to write S/370 assembler without comments? I thought I'd read the whole Book of Engineering Sins, but I must have missed that page.
I can only offer one comparable instance of evil, though in this case it was an evil development tool: a microassembler for a highly unusual synchronous communications device. This lashup had five parallel processors on it: an ALU, a microsequencer, a memory access controller, and two bus bridges. Its 48-bit-wide instructions had to address all five at once, with...interesting constraints and side effects regarding timing and conditional operation.
I was handed this device, the documentation for it (which was sketchy), and the existing microprogram for it, and told to make a range of enhancements to it. Imagine my surprise when I opened up that microprogram -- approximately 4000 instructions long -- and discovered that it contained not one single comment.
Needless to say, I immediately looked up the previous maintainer, who was overjoyed that the responsibility had passed from him, and inquired about the lack of commentary. He then told me the most incredible thing I've ever been told about a development tool:
"The microassembler doesn't allow comments."
It was true. I hadn't had any idea before he said so.
I spent the next six weeks, over the strenuous objections of my management, writing a new microassembler for the damned thing. Three years later, when the responsibility for the device passed from me to a young successor, the program was fully commented.
(This message is programming you in ways you cannot detect. Be afraid.)
|
|
|
|
|
Fran Porretto wrote: I spent the next six weeks, over the strenuous objections of my management, writing a new microassembler for the damned thing.
Fran Porretto wrote: There are really programmers who think it's okay to write S/370 assembler without comments? Yeah, unfortunately true. I left there after a year. The company declared bankruptcy the next day. I assume they decided without me there was no point in continuing.
But I got such delight in seeing their incredulous looks as they tried to decipher their own programs after a year.
While my programs were profusely commented, I might not have bothered, they had difficulty following what I was doing. One of my first programs was to do database maintenance (back when databases were flat files). Until I came there, the "largest" program was a deck about 2-1/2" to 3-1/2" thick. I ended up carting 1-1/2 cartons (~3000 lines of code) around. They thought I was trying to write a compiler. I figured I was going to be stuck doing more database maintenance (they tended to put people in silos) and by making a macro generated generic program that I'd just have to declare a few parameters and be able to gen a new system for any other database that came my way in no time. It was able to handle multiple commands (Edit, Modify, Change, all mean the same thing) because I wanted people to be able to use it without having to read the operation manual (or as I titled it, "Care and Feeding"). As you can tell, 37 years later and I still proud of it.
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.
|
|
|
|
|
Yes, because it's a lot easier to go to some unrelated business documentation and try to find the requirement which ties to this piece of code than it is to write a line or two in the file already being read about why this method exists.
Sigh.
I hope you're able to get this person educated/fired.
|
|
|
|
|
"any business documentation should be provided by the specification and not the code."
LOL nope. Code gets updated, specs rarely do, and that's assuming that specs even exist and can be easily found. Business logic is exactly the kind of thing that should be commented, because the logic of the code won't tell you that and specs don't often go into the kind of detail that is needed when debugging a specific implementation.
The code tells you what it does, good comments tell you why. The "why" is important, because you need to know what the code should do, not just what it does, because this is what a maintenance programmer really needs to know.
I was a maintenance programmer for a long time, and believe me, commenting business logic is important. The alternative is usually running around asking all the other programmers if they remember why this code--written by someone who is no longer there--is doing what it does.
|
|
|
|
|