ygolo
My termites win
- Joined
- Aug 6, 2007
- Messages
- 5,996
It's always better when we finally understand each other (and we're writing in english, kindof).
I am much closer to agreeing with you now.
I agree with that statement, mostly. "How" comments should be local to the code doing it (not outside the function or class), and only be used when the "how" is complicated or ambiguous in the code (in which case you may want to reconsider re-writing the code, also).
Maybe I just needed more context. I undertand that part of the comment, now to be some form of invariant, not simply what the code is doing--A big difference in interpretation.
The Invariant, Pre-Condition, Post-Condition paradigm is incredibly powerful, and a standard they used to teach everyone. I'm not sure when they stopped. A Discipline of Programming
But if you had a Japanese-English dictonary and could translate the words, Pre-Condition, Post-Condition, and Invariant, I'd bet you would have been helped out a lot. Since you could look for those standard markers, if the comments were done that way.
They are expected not to read your mind, but read the problem to be solved. I am fairly confident I could go back to code I wrote 9 years ago, refresh my memory of the problem to be solved, and understand what I was doing. The same is true when I read the code of other experience programmers (who also followed the "Discipline"). Again, the pre-condition, post-condition, invariant paradigm allows a programmer to map the problem to be solved (which usually forces invariants across the whole system) to the particular software artifacts you created (which individually will have invariants, if functioning properly).
But that doesn't keep you from "verbally teaching" others about your code.
Again, not mind reading, but problem reading. Experienced programmers use similar Design Patterns to solve similar problems over and over again. These can be fairly easily recognized if implemented in the clasical design patterns in an OO sytem. Design patterns have been around for longer than that term had been coined. There are slight variations, but there is a good reason that design memory is one of the few skills needed by all engineering disciplines. Learn to recognize and use the standard design patterns (at various levels) and you will make your work-life, and the work-lives of those that come after you much easier.
Don't use "I work in the real world" as an excuse not to make that world a better place. More documentation does not equal better documentation. Reference the design patterns you used, the invariants of your system, the pre-conditions and post-contitions where appropriate in your "English" documentation. This is not "nerd" speak. These are common words and idioms used by practicing software engineers and programmers, and is handy in whatever language(natural and programming) you are required to use.
I knew about Doxygen. Just following their format is better than "plain english". Because, then I can strip your comments if I find out they are not of much use.
I am much closer to agreeing with you now.
I think you are misunderstanding the point completely. I'll simply say .. Documentation isn't supposed to explain what the code does .. Documentation is supposed to explain the reasons why the programmer wrote what he did, when he did, and why he did .. Documentation should NEVER explain HOW he did, because the CODE is supposed to explain that part ..
I agree with that statement, mostly. "How" comments should be local to the code doing it (not outside the function or class), and only be used when the "how" is complicated or ambiguous in the code (in which case you may want to reconsider re-writing the code, also).
/*Add 3 to x*/ is a perfect example of bad documentation because it described exactly what the code does .. We both agree that anybody who is a programmer should be able to read the code, and figure that part out.
Documentation is supposed to explain to the next person reading the code, WHY the previous programmer did what he did .. "If all the attributes of the child node check out, then the child node hasn't changed"
Maybe I just needed more context. I undertand that part of the comment, now to be some form of invariant, not simply what the code is doing--A big difference in interpretation.
The Invariant, Pre-Condition, Post-Condition paradigm is incredibly powerful, and a standard they used to teach everyone. I'm not sure when they stopped. A Discipline of Programming
You know I won't get into people of different languages, because I did work on a project which was 100% commented in Japanese, but needless to say it didn't help that the "self-explanatory" variable names and such were also in Japanese. Yes it took a LOT of time reverse-engineering it and in those sort of cases its unavoidable. But that example is a worst case scenario in which case it really makes no difference whether or not you document at all.
But if you had a Japanese-English dictonary and could translate the words, Pre-Condition, Post-Condition, and Invariant, I'd bet you would have been helped out a lot. Since you could look for those standard markers, if the comments were done that way.
I never suggested that documentation is an alternative for proper coding .. However I'm not going to expect the next person who touches my code to expect to read my mind .. I don't document the programming language (C# in this case) .. I document my logic .. Why I wrote what I did ..
They are expected not to read your mind, but read the problem to be solved. I am fairly confident I could go back to code I wrote 9 years ago, refresh my memory of the problem to be solved, and understand what I was doing. The same is true when I read the code of other experience programmers (who also followed the "Discipline"). Again, the pre-condition, post-condition, invariant paradigm allows a programmer to map the problem to be solved (which usually forces invariants across the whole system) to the particular software artifacts you created (which individually will have invariants, if functioning properly).
I think expecting to be "verbally taught" by a former developer of the project is quite naive, since the case is more often than not that the former developer has quit the project. It tends to flow that way.
But that doesn't keep you from "verbally teaching" others about your code.
My audience is composed of fellow or future programmers, and myself, who are incapable of reading my mind and figuring out the logic I used to write the code by simple telepathy, or in my case, am subject gaps in my own memory due to not caring enough about a project to remember why I wrote what I did ..
Again, not mind reading, but problem reading. Experienced programmers use similar Design Patterns to solve similar problems over and over again. These can be fairly easily recognized if implemented in the clasical design patterns in an OO sytem. Design patterns have been around for longer than that term had been coined. There are slight variations, but there is a good reason that design memory is one of the few skills needed by all engineering disciplines. Learn to recognize and use the standard design patterns (at various levels) and you will make your work-life, and the work-lives of those that come after you much easier.
What can I say .. I'm expected to program in the real world whether i like it or not .. And in the real world documentation is required to be in english since more often than not, the paycheck comes from somebody who signs it in english.
Don't use "I work in the real world" as an excuse not to make that world a better place. More documentation does not equal better documentation. Reference the design patterns you used, the invariants of your system, the pre-conditions and post-contitions where appropriate in your "English" documentation. This is not "nerd" speak. These are common words and idioms used by practicing software engineers and programmers, and is handy in whatever language(natural and programming) you are required to use.
By the way, I did google this subject since I was curious what the thought on this topic was and needless to say its a hot debate that isn't solved elsewhere ..
Linux.com :: How to document your code
However thanks to our discussion and my following "research" I found an amazing documenting resource called Doxygen which automatically generates external HTML documentation for your code. It will give summaries and such as well provided they were documented in the first place in the code. I think you should check it out cuz I found it pretty amazing.
Doxygen
I knew about Doxygen. Just following their format is better than "plain english". Because, then I can strip your comments if I find out they are not of much use.