Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

my question is rather a matter of English language. For proper commenting my code I want to know when you do for example the following code, what comment you can write for it?

public class TestClass
{
    public double volt {get; set;}
    public double curr {get; set:}
} 

Somewhere else in the same namespace

public class AnotherTest
{
    TestClass test;

    public AnotherTest(TestClass test)
    {
       this.test = new TestClass(); //how to comment this?
    }
}
share|improve this question
4  
Why would you comment that? It's self explanatory? Also, should it not be this.test = test, or are you doing something else with the constructor parameter? –  Darren Young Oct 31 '11 at 8:19
    
Well I give up commenting that line, can you tell me what is the most professional way to name what is happening in that line? Since I saw different names for it. –  Sean87 Oct 31 '11 at 8:23
    
use instantiate when you are allocation memory as in this case when you are creating a new object. See this post: stackoverflow.com/questions/2330767/… –  Filip Oct 31 '11 at 8:40
2  
In you case, you are instantiating the object. However, I think your line of code should read this.test = test. In that case you are initialising, as more than likely, the TestClass object that you are passing into the constructor would already have been instantiated else where. As a base rule, instantiation is where you create the object, initialisation is where you give it some value. –  Darren Young Oct 31 '11 at 8:40
    
The best advice for how to comment this line is to not comment it. Take a look at Comment Only What the Code Cannot Say from 97 Things Every Programmer Should Know. –  Mark Booth Oct 31 '11 at 15:42

1 Answer 1

up vote 9 down vote accepted

You don't need comments in the example given. You need better variable names.

Use the following rules to judge the value of a comment:

  1. Comment on specific implementation of a piece of logic or business rule or program modification log, or feature change

  2. Never comment on language syntax inside the code (as in your case) - The developer should know the syntax

  3. Comment on a specific choice of a computing approach such as useing Instr instead of Regex that could result in performance gain

  4. Add comments to describe specific usage of variables and methods to avoid unnecessary long names or to clarify the purpose for the reader quickly.

  5. Too many comments are useless and harmful sometimes, especially if not maintained.

  6. The code is not the only place for comments.

  7. If you are working on a project, have some guidelines.

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.