Tagged Questions
14
votes
3answers
7k views
What javadoc equivalents do you use in .net? [closed]
Java developers use Javadoc in order to write inline documentation in their comments. What are the alternatives for .net - specifically c# and VB.net that people actually use in real world projects?
5
votes
3answers
194 views
Commenting regular expressions
Are there any common practises for commenting the regular expressions: inline comments referring different part of RegEx or general comment for all expression?
6
votes
7answers
706 views
In what stage of development should comments be written?
I'm a student working an internship at a larger company, writing small business apps in C#. I've noticed that I don't comment my code as I write it. Rather, I comment my code when I'm in the ...
6
votes
3answers
395 views
Are XML Comments Necessary Documentation?
I used to be a fan of requiring XML comments for documentation. I've since changed my mind for two main reasons:
Like good code, methods should be self-explanatory.
In practice, most XML ...
9
votes
6answers
690 views
Are comments considered a form of documentation?
When I am writing small scripts for myself, I stack my code high with comments (sometimes I comment more than I code). A lot of people I talk to say that I should be documenting these scripts, even ...
3
votes
6answers
458 views
Should you use “internal abbreviations” in code comments?
Should you use "internal abbreviations/slang" inside comments, that is, abbreviations and slang people outside the project could have trouble understanding, for instance, using something like //NYI ...
5
votes
6answers
561 views
Should I add MSDN notes or Stack Overflow links to source code? [duplicate]
Possible Duplicate:
Is it OK to put a link to Q&A sites in a program's comments?
I'm creating a powershell / C# host and want to add the following comment
// This method cannot be ...
7
votes
2answers
278 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?
48
votes
16answers
3k 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 ...
2
votes
5answers
440 views
Why should you document code? [duplicate]
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. ...
8
votes
5answers
271 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 ...
3
votes
8answers
3k views
Is there a symbol or shorthand for “and is increasing/decreasing”?
This usually happens when I'm writing to developers or other IT professionals.
The context would be something along the lines of ". . . measured at 100 MB/s (and is increasing)."
On paper or a ...
21
votes
13answers
2k views
When do you start documenting the code?
Some friends and I recently started a medium-size project. We already covered the design part (at least the first attempt) and now we are moving into coding. We already have implemented some objects ...
5
votes
7answers
568 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 ...
1
vote
1answer
160 views
Metrics: Comments vs Documented API
I've been asked to run some code metrics in order to assess the quality of the code. One of the metrics was vaguely specified as "comments".
I ran Sonar on my code, and while I got 10% on the ...
