Tagged Questions

14
votes
3answers
989 views

How to solve the problem of nested comments

It appears in not just one language that comments can't be nested. Do you have a good solution for this problem? One workaround in C/C++ and Java is to only use the single-line comment but it becomes ...
13
votes
2answers
634 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 ...
12
votes
6answers
2k 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 ...
9
votes
7answers
517 views

Writing documentation for well understood methods like equals in Java

Is it a good practice to write comments for widely known methods like equals, compareTo etc? Consider the below code. /** * This method compares the equality of the current object with the ...
7
votes
6answers
917 views

Is it necessary to write a javadoc comment for EVERY parameter in a method's signature?

One of the devs on my team believes that it is necessary to write a javadoc comment for EVERY parameter in a method's signature. I do not think this is necessary, and in fact I think it can even be ...
5
votes
7answers
589 views

Is it wrong not to create Javadoc for my code?

I do a lot of Java programming at my work (I'm an intern) and I was wondering if it is generally a rule to create javadoc to accompany my code. I usually document every method and class anyways, but I ...
3
votes
1answer
3k 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 ...
2
votes
3answers
287 views

Where should I include comments in my “self-documenting code”?

I'm currently developing a web-app by myself and have made it a point to use descriptive variable and method names (sometimes at the expense of brevity) in order to minimize commenting. The plan was ...
1
vote
2answers
101 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 ...