3
votes
2answers
336 views

Asterisks in Multi-line comments

Using Visual Studio 2012 with C#, when I write multi-line comments, VS automatically begins each line with an asterisk, like this: /* * * */ I was just curious if this was the case in ...
15
votes
4answers
1k views

Is the “Gets or sets ..” necessary in XML documentation of properties?

I am looking for a recommendation of a best practice for XML comments in C#. When you create a property, it seems like that the expected XML documentation has the following form: /// <summary> ...
13
votes
2answers
957 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 ...
6
votes
3answers
530 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 ...
5
votes
4answers
220 views

Should I comment Tables or Columns in my database?

I like to comment my code with various information, and I think most people nowadays do so while writing some code. But when it comes to database tables or columns, I have never seen anyone setting ...
2
votes
4answers
284 views

Linking in code comments (to other unique anchors/comments)

How would you recommend creating "anchors" in code comments, so that during maintenance, developers can easily cross-reference other code comments. I realise that software should be intelligently ...
14
votes
11answers
778 views

Is it efficient to attach a comment on every function?

I moved to this company recently, and my first reaction of the development process leaves me with doubts. Here is where I really doubt the efficiency: Every single function must have Javadoc style ...