I feel that it is important to comment your code and make sure that the next developer that uses the project knows what the hell you have done. However I have seen over the time I have been developing a lot of different ways people comment, so here are some of the dos and do nots with comments. This will give the final answer as to what people think is the best method to comment and why?
As you would know reading this there are many languages and methods to commenting. Some are particular to the coding language itself like ASP.NET. In C# ASP.NET you can /// above a method to attach comments about what it does, uses and delivers. However in JavaScript you don’t get this ability, so to say the best method is the C# ASP.NET method is wrong. Instead it is more about the fails I feel people make in general, for which I will use particular languages as examples.
I have seen when people give a massive explanation into what and why this method is here. This is should be an example to the developer the code is to complex. Change the method so you don’t need that many comments.
Adding your life story:
// This is a big file I thought would be very good to have
//You might have to look at the middle or the top.
//It will help to look at this file.
//Don't forget to save it
The below is a bit over the top, but then again you do find some that find the need and the time to construct this. However I do see the creative kind that make the comment contained in a nice box with tables etc. This is not just a waste of space, but also of bits of data. I know it is small space it is taking, but it adds up if you are trying to make it as fast as possible.
The designer:
/*
(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)
|| M || || O || || N || || K || || E || || Y ||
(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)
-It’s Monkey Business Time! (Version 1.5)
*/
There are the developers that feel the file should contain there version control and bio of the file. If you are using version control like Git or Team Foundation Server, then you shouldn’t need this. It is a bit like above, waste of space and data but at least it is somewhat useful.
Comments version control:
' method name: FooBar (included for the sake of redundancy)
' created: Feb 18, 2009 11:33PM
' Author: Johny
' Revisions: Sue (2/19/2009) - Lengthened monkey's arms
' Johny (2/20/2014) - Solved drooling issue
'
A simple thing people do not understand is to comment in HTML it is only two dashes. I have seen some developers try to separate their whole code like break points with this. The example below will fail W3C Validation, which is then not good for you site.
Over usage:
<!--------------------------------------------------------------------New sections -------------------------------------------------------------------->
Another example of what developers do is comment everything, which I find slightly insecure as these comments are visible to the people view the sites source code unlike backend code like C#. I have seen things like this…
Security Risk:
<!-- will get injected with content by table Passwords_Table -->
So how can we make better comments? Well My preferences are simple but effective.
I have a key to how I do different titles for sections like in CSS:
/* == MAJOR SECTION HEADING ==*/
/* — Minor Section Heading —*/
I would make sure that I don’t over bloat my code with comments and name classes/ids relevant like in HTML:
< div>
<!-- Top Part -->
< div class="top_part">
< /div>
<!– Middle Part –>
< div class=”middle_part”>
< /div>
<!– BottomPart –>
< div class=”bottom_part”>
< /div>
< /div>
< /div>
A good source I found for valid HTML comments for the different html versions is at mozilla.
In ASP.NET, as mentioned before, you also have the ability to create a method summary. To do this you do the comment character 3 times above the method. This then automatically add the summary tag and all the parameter tags. Not only does this give a brief comment about the method, but when you use it in various other places it will have a tooltip with the information in. This then means you don’t have to hunt down what, why, when of the method you are about to use.
/// <summary>
/// This Method opens a door
/// </summary>
/// <param name="key"> key opens the door </param>
/// <param name="code"> code is the code for the door </param>
private void OpenDoor(string key, string code) {}
As I said before I believe in simple meaningful comments, instead of a paragraph. If you are doing any of the above fails, then I think you need to rethink your comments or maybe even your code. It is meant to be readable by any other developer, so the key feature is does it make sense.
I reached out to some fellow developers on my Google+ Network and they had the same idea.
Eric Fischer
Good code is nearly self-explainable. Name your variables that they describe what they are used for. If you write a lot of methods: a little explaination in form of a small JavaDoc above the method could be useful. Too much commenting reduces the readability. Use comments for lines of code in your method if they are complicated to read or to understand.
From https://plus.google.com/u/0/115759722116880665817
Here are all the other comments and thought on Programming Community and Web Development Community.
I would be very interested to know how you comment and what techniques you find work best for your coding language of choose. Comment below your thoughts.
PR Code 