|
I use source control and check in with relevent comments - you have
no idea how many times I have been able to point to that in code for a client
and say "No, noone has changed this since..." which is particularly handy if
something strange goes on.
|
|
|
|
|
Bollocks.
I wanna be a eunuchs developer! Pass me a bread knife!
|
|
|
|
|
That's obviously a lie. Self documenting functions are nice, but you can't do anything nontrivial that way.
Then again, maybe his code only does trivial things? 
|
|
|
|
|
Round flying thing.
Discus.
|
|
|
|
|
|
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(); }
}
|
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
