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.

After many years of coding, trying various programming styles, weeding out unreadable or impractical stuff, I still can't figure out one thing: what is the best way to single-line-comment multiple lines of indented code.

1.

    setup_checkpoint();
//    if (object->looks_suspicious())
//        guard->full_body_scan(object);

2.

    setup_checkpoint();
    // if (object->looks_suspicious())
    //     guard->full_body_scan(object);

3.

    setup_checkpoint();
    // if (object->looks_suspicious())
        // guard->full_body_scan(object);

Please, don't suggest multiline commenting, because sometimes you want to leave that possibility for bigger blocks, which may include smaller pieces of comments.

share|improve this question

6 Answers 6

Since you do this for testing purposes, you normally want to have that stand out as much as possible, so you don't overlook removing the comments or the code later. Comment markers on the left margin are more visible.

share|improve this answer
    
Yes, except it's not always for testing purposes. Sometimes you leave a few commented lines of code as a message, e.g. "this could have been here" or "might come back one day". Customer's requirements, you know, they come in an arbitrary and illogocal manner. In these cases (longer-term commenting) I go for 2 or 3. –  mojuba May 11 '11 at 15:01
2  
"Might come back one day" is what source control is for. –  whatsisname May 11 '11 at 15:05
1  
@whatsisname: look through 1500 updates to see which one to revert back? –  mojuba May 11 '11 at 15:09
    
@mojuba: wouldn't you realistically have some other criteria to apply when searching rather than looking through the entire commit history? And if you're looking to revert that 1-in-1500 change and finding the particular commit is too much trouble, wouldn't it be simpler to reimplement given the current conditions? If it'll take three hours to find / revalidate (nothing is ever exactly the same as before) / retest or one hour to reimplement & test, reimplementation seems to be the better choice. ('three hours' is pulled outta my backside and has no particular significance) –  DaveE May 11 '11 at 16:29

This is how Visual Studio does it when you click the comment selection button:

    //private void Parse()
    //{
    //    while (_InputQueue.Count > 0)
    //    {
    //        switch (ParseState)
    //        {
    //            case AvailableStates.Begin:
    //            case AvailableStates.Found_ETX:
    //                byte FirstByte = _InputQueue.Dequeue();
    //                if (FirstByte == STX)
    //                {
    //                    ParseState = AvailableStates.Found_STX;
    //                }
    //                break;

I think it works well and looks nice. Of course the syntax highlighting accounts for probably half of the 'quality'

share|improve this answer

When I comment out code I always put the comment before any indentation since, as @David Thornley says, it stands out better when browsing through the code. Also, as I use vim, it's easy to insert/delete the comments in visual block mode without messing up any indentation.

share|improve this answer

Whatever you like. You are not supposed to leave things like that for more than the time of fixing some issue, right? So it will disappear in a few minutes.

If instead you are actually using code like that for longer times, that is a different issue. Just remove the blocks you don't need and use version control to be sure you will be able to find them again in case you need them in a month.

share|improve this answer
    
Yes but: like I said elsewhere in this thread, longer-term commenting of code is not uncommon, and version control may not always be practical for this purpose if you have hundreds or thousands of updates already. –  mojuba May 11 '11 at 15:11

Eclipse does it the way you have displayed it on example 1 and personally I find this way much more readable than the others.

share|improve this answer

There is no objective "best" was - every style is valid and there might be personal preferences for each of these three styles.

Personally, I always use the first style (having the // starting on the first column) since that's the default settings for most IDEs I know of and it simply looks good.

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.