|
Alex,
We'll have to agree to disagree on this.
AlexCode wrote: So my point is that if you really respect a good set of coding guide lines, your comments will be minimal and usually only at the class level, occasionally at the method level and never inside the methods.
I can't ever imagine saying that developers can't comment their code inside a method. I often comment things I'm doing. There is nothing worse than being the new guy and having no comments to provide some context to what's going on inside code. Yes the code is the final answer, but somethings it helps to read the Cliff Notes before you start. Not everybody is a subject matter expert.
Hogan
|
|
|
|
|
I agree with you in the sense that we should always comment.
The thing I don't agree is the comments inside the methods.
Comment the classes describing the purpose of it. You can go crazy here and detail everything that this class is meant to do.
Comment the methods when the name is not self explanatory.
Now, after this, if you feel the complexity of a method is such that it needs inner explanation maybe it's time for a refactoring. Most likely that method is doing a lot of stuff and if you think about making some unit tests on it you won't be able to test a single thing but a whole complex behavior.
Usually the argument for not doing this is that you'll end up with several methods that are only called once...
Ok, I agree, it's not pretty but it's testable and very easy to maintain.
It's the difference between that new guy in the team facing a very complex method with 250 lines of code or the same thing split between 10 methods of 25 lines each.
Or between an IF with 2 ELSE conditions, each with 20 lines of code or each calling a different function.
What I'm saying here is that if we split the code it will be much easier to read making it redundant to comment.
P.S.: This is a guide line not a religion. Keeping this in mind will hopefully put you somewhere in between 
Cheers!!
|
|
|
|
|
We used "documentation" to define the requirements. Plain english and "business speak"...that way the business could describe any changes they needed but we also had a description of what the code was supposed to do. Of course that didn't always mean that that was what it actually did  Depends on the field I guess.
|
|
|
|
|
|
I've had numerous discussions at work whether or not to comment and/or document code.
After seeing lots of much documented, but poorly documented code I came to the conclusion that code does not lie while comments might.
Whether or not you are going to read the comments and/or documentation you'll always have to read the code too to see if it actually does what the documentation says (and in my experience it often doesn't).
In a worst case scenario you'll end up with a simple software change that takes hours to fix because you need to change the documentation in numerous places.
I prefer to keep documentation and comments to an absolute minimum and just write clean code that is (hopefully) easy to read.
|
|
|
|
|
I'm with you on this. Clean code is important, but the documentation should be consistent, too.
For example, documenting the fields of a class in the class' comment header is BS, while documenting each field of a class is helpful. If now someone comes and uses a field the wrong way, not the documentation but the code is not clean.
I will never again mention that Dalek Dave was the poster of the One Millionth Lounge Post, nor that it was complete drivel.
How to ask a question
|
|
|
|
|
Certainly, in regard to comments within code, the policy should be if you can express it clearly in code than do that rather than comment it. E.g., an easy technique is to assign conditionals to well-named boolean variables rather than comment them.
I find that while I'm writing code initially I will add section comments to guide my thoughts. Then when the algorithm or method is finished I will refactor it so that, e.g., the section comments themselves become well-named methods. At the end there will ideally be zero comments.
Kevin
|
|
|
|
|
Some people seem to be able to write good code, but present it in such a way that you can't work out what the heck is happening...
Though as a general rule, code is getting easier to read as a result of improvements in the editors we use: auto indent is an absolute godsend!
Those who fail to learn history are doomed to repeat it. --- George Santayana (December 16, 1863 – September 26, 1952)
Those who fail to clear history are doomed to explain it. --- OriginalGriff (February 24, 1959 – ∞)
|
|
|
|
|
Start with documentation then go to code
|
|
|
|
|
... without going into specifics the answer will always be "it depends".
|
|
|
|
|
I think Technical person always like to read code first.
Rating always..... WELCOME
The only reason people get lost in thought is because it's unfamiliar territory.
|
|
|
|
|
I agree. The code is more concise is most cases, and you will only read the comment if the code is really strange / complicated, or doing something stupid for a good reason (squashing exceptions)
My plan is to live forever ... so far so good
|
|
|
|
|
Agree
|
|
|
|
|
In my opininon comments must contains explanation of algoritms and link to sources of information, link to KB and focus on theories, not dissertation on the code.
If you program you must understand flow, what you need is a quick presentation of choices taken and who is responsible for business rules.
So both must be read, or (I dont know your experience) MUST BE WRITTEN.
Cheers.
|
|
|
|
|
|
Sorry[^]
thatrajaCode converters | Education Needed
No thanks, I am all stocked up. - Luc Pattyn
When you're wrestling a gorilla, you don't stop when you're tired, you stop when the gorilla is - Henry Minute
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
