Tagged Questions
Questions about comments and documentation in code, including best practices and techniques for commenting and documenting.
6
votes
2answers
95 views
DRY way to write Javadoc on overload methods
I want to write Javadoc in DRY way. But the oracle document about Javadoc says write same thing again in overload method comment. Can't I avoid repetition?
8
votes
7answers
399 views
Use of NotImplementedException
Is it considered bad practice to throw NotImplementedException for code you haven't written yet? Possibly TODO comments would be considered safer?
10
votes
6answers
449 views
Best practices in comment writing and documentation
Commenting nowadays is easier than ever. In Java, there are some nice techniques for linking comments to classes, and Java IDEs are good at making comment shells for you. Languages like Clojure even ...
4
votes
7answers
635 views
Why does everybody write to-do comments in capital letters?
I'm doing the same. When there is something "to-do" in my code, I write //TODO .... But I'm curious to know when this started and if there is a reason for writing "to-dos" in all capital letters?
15
votes
13answers
853 views
Comment before or after the relevant code
Assuming a comment won't fit (or can't go) on the line it applies to, should one write the comment before the code or after?
Well, wherever future readers will best understand the comment's scope. In ...
15
votes
10answers
884 views
Are chatty/humorous comments in source code acceptable or unprofessional? [closed]
Possible Duplicate:
Humor in Documentation
Throughout my professional career, I have often relied on chatty or humorous comments in source code (or source control commit messages) to help ...
-3
votes
3answers
154 views
Is it a good practice by commenting with owner name? [closed]
Possible Duplicate:
How do you keep track of the authors of code?
Here's several scenarios which may comment with owner name:
bug fixing, i.e. // fixed bug 123 by xxx, solution is ... ... ...
42
votes
16answers
2k views
Do TODO comments make sense?
I am working an a fairly big project and got the task to do some translations for it. There were tons of labels that haven't been translated and while I was digging through the code I found this ...
9
votes
11answers
434 views
What should I put in comments while commiting to the Source Control?
I am a lone developer and maintain a SVN server for source control. So far, I haven't followed anything specific while committing my changes.
I was just reviewing my previous commits, and couldn't ...
1
vote
5answers
273 views
Why should you document code? [closed]
Possible Duplicate:
“Comments are a code smell”
I am a graduate software developer for an insurance company that uses an old COBOL-like language/flat-file record storage system. ...
4
votes
1answer
111 views
Should code comments have scope?
I am asking this because I have seen places where, whoever coded initially had provided proper comments, but later on modifications were made to the code but the comments were left untouched. I ...
24
votes
7answers
997 views
Should one comment differently in functional languages?
I'm just getting started with functional programming and I'm wondering about the correct way to comment my code.
It seems a little redundant to comment a short function as the names and signature ...
14
votes
5answers
581 views
Beginner's guide to writing comments?
Is there a definitive guide to writing code comments, aimed at budding developers?
Ideally, it would cover when comments should (and should not) be used, and what comments should contain.
This ...
8
votes
5answers
199 views
Should a method comment include both a summary and return description when they're often so similar?
I'm a proponent of properly documented code, and I'm well aware of the possible downsides of it. That is outside of the scope of this question.
I like to follow the rule of adding XML comments for ...
1
vote
1answer
126 views
instantiate or initialize when using a new class?
my question is rather a matter of English language. For proper commenting my code I want to know when you do for example the following code, what comment you can write for it?
public class TestClass
...
