|
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
