Slashdot Mirror
What is Well-Commented Code?
WannaBeGeekGirl queries: "What exactly is well-commented code anyway? Can anyone suggest resources with insight into writing better comments and making code more readable? After about six years in the software development industry I've seen my share of other people's code. I seem to spend a lot of time wishing the code had better (sometimes _any_) comments. The comments can be frustrating to me for different reasons: too vague, too specific, incoherent, pointing out the obvious while leaving the non-obvious to my imagination, or just plain incorrect. Poorly or mysteriously named variables and methods can be just as confusing. In a perfect world everyone would follow some sort of coding standards, and hopefully those standards would enforce useful comments. Until then, any suggestions for what you, as a programmer, consider to be good/useful/practical comments? Any suggestions for what to avoid? Also, I usually work with C++ so any resources/comments specific to that language would be too."
The best comment is the code.
A True Klingon Warrior does not comment his code.
That statement holds something very valuable in it.
If someone can't understand your code without comments, then it's either a) too complicated, or b) the fact that this said person has no right to be anywhere near your code, let alone daring to modify it.
If they need to see it in English (Or any other language aside from the language it is written in), chances are, they will screw it up when they think they 'know' what it does.
Microsoft rant. Please mark parent:
(-1, Offtopic)
"Microsoft Press also publishes a magnificent book called "Writing Secure Code""
Oh the irony of it all - I suppose the second in the series is entitled "Writing a Secure OS" or "Writing an OS for Dummies"
Video Game cheats, hints a