Tagged Questions
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
705 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
391 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
689 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 ...
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
274 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
431 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
268 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 ...
1
vote
1answer
156 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 ...
2
votes
5answers
291 views
Run On Sentences in Technical Writing
This is just a question to think about.
When you write technical documentation and programming comments, do you ever find yourself writing run-on sentences in order to be more precise?
Is packing ...
5
votes
7answers
562 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 ...
7
votes
6answers
816 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 ...
