|
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
|
|
|
|
|
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
