Tagged Questions
1
vote
2answers
93 views
@Deprecated as of version x.y in JavaDoc
This question & its answers are useful but not sufficient for my problem.
My Question is if I want to add a javadoc as @Deprecated As of version x.y, replaced by {@link SomeClass} in my current ...
13
votes
2answers
617 views
What is the best approach for inline code comments?
We are doing some refactoring to a 20 years old legacy codebase, and I'm having a discussion with my colleague about the comments format in the code (plsql, java).
There is no a default format for ...
20
votes
8answers
1k views
Should comments say WHY the program is doing what it is doing? (opinion on a dictum by the inventor of Forth)
The often provocative Chuck Moore (inventor of the Forth language) gave the following advice (paraphrasing):
"Use comments sparingly. Programs are self-documenting, with a
modicum of help from ...
3
votes
1answer
207 views
Is there an industry standard for structuring code and comments?
I've worked with a number of professional teams and it seems that class code structure ranges from highly organized to completely cluttered. I did a project with the State of California recently and ...
3
votes
1answer
2k views
What is the best way to comment a deprecated class in Java?
I would like to know the best way to add a comment to identify a deprecated class in Java. Should I remove the previous comment added to the top of the class that helps another programmer to know what ...
25
votes
17answers
2k views
Why would company develop an atmosphere which discourage code comments?
I was taught in University to write comments for our programs. As I write comments, I feel like I have a better organization and understand the programs better.
However, I am in a company where most ...
0
votes
6answers
384 views
What information should a good (method- / class-) comment contain?
This is something that has bothering me for a while now. I guess there are a couple of obvious important things that should go into a comment, such as:
The author(s)
A description of the parameters ...
0
votes
4answers
166 views
Emphasize Some Comments - but not Dirty the Code
I'm having trouble structuring my comments at the moment.
I have major sections of the code that, when scrolling through the document, I want to be able to see those stand out.
Examples:
This is ...
24
votes
13answers
2k views
Is commented out code really always bad?
Practically every text on code quality I've read agrees that commented out code is a bad thing. The usual example is that someone changed a line of code and left the old line there as a comment, ...
4
votes
4answers
264 views
Correct alignment when outcommenting code
Suppose I have some code
void some_block(void)
{
some_statement_1();
some_statement_2();
some_statement_3();
}
Now I wish to out-comment statement #2, but here I never can find a way ...
