Questions about writing comments in code.

learn more… | top users | synonyms

0
votes
3answers
116 views

Should method comments be written as if everything will work?

If I have a method to look for a valid email address in an array, that could either: Return the email address Return false if an email wasn't found. Throw an exception if an email was found, but it ...
0
votes
4answers
244 views

Deciphering foreign code [duplicate]

What is the best strategy to go about understanding some one else's code for a medium sized project, if the code is not well documented and does not adhere to many coding standards?
9
votes
5answers
1k views

Annotate source code with diagrams as comments

I write a lot of (primarily c++ and javascript) code that touches upon computational geometry and graphics and those kinds of topics, so I have found that visual diagrams have been an indispensable ...
2
votes
7answers
1k views

Should you use “internal abbreviations” in code comments?

Should you use "internal abbreviations/slang" inside comments, that is, abbreviations and slang people outside the project could have trouble understanding, for instance, using something like //NYI ...
2
votes
2answers
535 views

Documenting the effect of std::move

As my team move towards embracing the new features in C++11, I'm struggling with how to make the side-effects of std::move self-documenting in the code. The issue is that an object that has been ...
4
votes
3answers
768 views

How should one properly comment and license a set of code files before uploading to the public? [duplicate]

I've written a decent chunk of code over the past few days and I'm ready to git init it and push it to github. But before I do so, I want to do this the "correct" way in case anyone else wants to use ...
66
votes
17answers
11k views

Do TODO comments make sense? [closed]

I am working on 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 ...
43
votes
11answers
12k views

Why are /// comment blocks important?

Someone once said we should prefix all our methods with the /// <summary> comment blocks (C#) but did not explain why. I started to use them and found they annoyed me quite a bit, so stopped ...
28
votes
4answers
3k views

How are comments usually parsed?

How are comments generally treated in programming languages and markup? I am writing a parser for some custom markup language and want to follow the principle of least surprise, so I'm trying to ...
16
votes
6answers
5k views

Best practices in comment writing and documentation

Commenting nowadays is easier than ever. In Java, there are some nice techniques for linking comments to classes, and Java IDEs are good at making comment shells for you. Languages like Clojure even ...
2
votes
4answers
124 views

Should actions / methods be conjugated in comments?

For example, which of the following is correct ? // Return hello -- or -- // Returns hello function greeting() { return "Hello"; } I personally never conjugate them but I am wondering how ...
0
votes
1answer
81 views

Should I document expected call-sequences when call-order matters?

In dynamically and weakly-typed languages*, I often find myself with structures like the following pseudocode: class Stateful: # [ various datamembers / attributes / properties / fields / etc. ] ...
-2
votes
4answers
115 views

Best possible way to comment? [closed]

My question is simple, how should I comment during development so that it can be beneficial in the following cases: Understandable for my seniors while code reviewing. Should be able to search my ...
2
votes
2answers
181 views

Is there anything wrong with putting comments in an HTML closing tag?

I often write comments like this <div id="wrapper"> ... </div> <!-- id="wrapper" --> But what if I wrote them like this? <div id="wrapper"> ... </div id="wrapper"> ...
0
votes
3answers
185 views

In the spirit of consistency, is it acceptable to comment everything equally? [closed]

Consistency is something I value (at an OCD perfectionist level to be honest). I can live with not writing any comments and focus on producing good, refactored, readable code -- or, if I must comment, ...
10
votes
4answers
1k views

Why should comments / documentation of a JavaScript function include so much? [duplicate]

I was researching proper commenting practices for JavaScript and highly upvoted answer (+100) cites JSDoc-like commenting. JSDoc promotes comments like this: /** * Represents a book. * @constructor ...
16
votes
7answers
1k views

Writing comments for some small code with rather large background [duplicate]

So I had to write some code related to splitting Bezier curves into parts. I read through several references and particularly referred this rather detailed one. The final code outcome is however ...
22
votes
6answers
3k views

Explaining new or uncommon syntax in comments [duplicate]

As per the title, should I be explaining syntax that I use in my code when I have a reasonable expectation that a developer looking at my code in the future will not be familiar with it? Short caveats ...
68
votes
9answers
8k views

Clean Code comments vs class documentation

I'm having some discussions with my new colleagues regarding commenting. We both like Clean Code, and I'm perfectly fine with the fact that inline code comments should be avoided and that class and ...
65
votes
13answers
9k views

Can commented-out code be valuable documentation?

I wrote the following code: if (boutique == null) { boutique = new Boutique(); boutique.setSite(site); boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo()); ...
9
votes
3answers
233 views

How to refer to specific areas of code in documentation?

I'm about to leave a project, and before I go my boss has asked for me to document code (I've not documented very well). It's not a big deal, the project is not terribly complex. But I'm finding ...
4
votes
3answers
165 views

Is there a difference between the quotes in `help',``help“, 'help' and ”help"?

Sometimes I find in the source code files comments have quotation marks like these ,notice the ` : `help' ``help" For example, these are comments from GNU cat source code file, cat.c: /* Plain ...
168
votes
23answers
15k views

How can I deal with a team member who dislikes making comments in code?

One of my team members consistently avoids making comments in his code. His code is not self-documenting, and other programmers have a difficult time understanding his code. I have asked him ...
1
vote
1answer
160 views

What is ## used for?

I have looked at other questions about this and the general consensus seems to be that ## is used for commenting out code. However, in the Interactive Editor for Python, prefixing a line with ## ...
13
votes
9answers
594 views

Please share experience on how to make the source code easy for other to follow? [closed]

I can write source code in a period of time, but after a while of not touching the project, it takes me time to be familiar with the source code again. Also, other people need some time to study the ...
3
votes
3answers
291 views

Should code comments explain the control flow?

Should comments explain how the application control flow works? For example, the relationships between classes, how this function is used by other functions, and what we are trying to do with these ...
70
votes
17answers
15k views

How can I ask my boss (in a polite way) to comment his code?

I am being taught by my boss (I just finished school and he wanted someone with a little programming experience, so he chose me to train me on what that company specializes in) and started working ...
190
votes
16answers
33k views

What's wrong with comments that explain complex code?

A lot of people claim that "comments should explain 'why', but not 'how'". Others say that "code should be self-documenting" and comments should be scarce. Robert C. Martin claims that (rephrased to ...
8
votes
3answers
1k views

Is reading javadoc preferable to reading source code to familiarise yourself with a library?

I just came across the following in a lab manual at university: You do need to study the interfaces of the classes by generating the javadoc for them so you know what operations are provided (feel ...
0
votes
1answer
66 views

Comments for a class that isn't an entity

According to Java's commenting conventions, classes comments should describe a "thing", rather than "actions". It is easy when the class IS a thing (ex. a Clown), but what if it isn't? In this case, ...
2
votes
4answers
416 views

How does a developer code in anticipation of change? [closed]

I ask this question based on the fact that currently my environment is under constant change due to the type of work we do. We do not always work on a project bases we often have smaller changes that ...
0
votes
2answers
567 views

Commenting Code AS3 - Not being an API

How should I comment a method? What are the best practices on commenting code? Example: /* Checks if a color is allowed in a given point * of the bitmapdata of the current floor * @param value - ...
3
votes
3answers
185 views

Is it misleading to label code as a particular design pattern if it only loosely fits the definition?

Background: I have a rough, but working understanding of ~15 design patterns. It's been my experience using design patterns in my own projects that the resulting implementations usually end up as some ...
19
votes
3answers
5k views

How to solve the problem of nested comments

It appears in not just one language that comments can't be nested. Do you have a good solution for this problem? One workaround in C/C++ and Java is to only use the single-line comment but it becomes ...
-1
votes
7answers
274 views

Single line comments for multiple indented lines of code [closed]

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 ...
2
votes
1answer
884 views

Possible to Comment on a storyboard?

I recently started working for a company that has me making mockups for an app they'd like to see converted to an iPhone app. I have not been informed as to how all the boards fit together, but I do ...
1
vote
1answer
168 views

Is there a particular coding standard with comments between function name and body?

I'm integrating with a shipping API built in php. They have a strange coding standard where the comments are between the function name and the first curly bracket.. which - subjectively - makes the ...
1
vote
3answers
93 views

Should I mark what blocks mean in data-* attributes?

I was writing a webpage today with a comment after the start of every major section. Instead of using a comment, which comes with the bulgy <!-- --> syntax, could I instead put this in a data-* ...
0
votes
2answers
156 views

Referencing StackOverflow questions in comments [duplicate]

Often when coding I'll get stuck on a particularly tricky problem and will go about searching for a solution. More often than not this leads me to a StackOverflow question that provides a full or ...
1
vote
3answers
200 views

Is there a need to comment obvious parameters? [duplicate]

Most of the time, when I comment a method, I'll follow this structure. /** * Short description of what the method does * * @param {Type} name. Description of the variable. * * @return {Type}. ...
4
votes
3answers
541 views

Intentionally incorrect use of language features, specifically “ref” in C#, as a hint to colleagues

I recently came across a piece of code something like this (roughly C#): public bool ValidateStuff(ref ArrayList listOfErrors, Stuff thingsToValidate) { if (!thingsToValidate.isValid() ) { ...
18
votes
12answers
2k views

Correct comment to put for boolean function arguments that are “false”?

From some open source projects, I gathered the following coding style void someFunction(bool forget); void ourFunction() { someFunction(false /* forget */); } I always have doubt about what ...
0
votes
0answers
36 views

Changelog in Comments Versus Source Control Log [duplicate]

Until recently, I have worked on a code base which kept change logs both as a table in the header section of each file and as comments in source control. In practice, only the header comments were ...
0
votes
2answers
165 views

How to systematize tagging in code? [closed]

There are several almost standard tags used in comments: FIXME, TODO, BUGBUG. Which other tags do you use and for what? Are there any standards on using them, i.e. format (supplementing with date ...
6
votes
7answers
553 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?
5
votes
6answers
5k views

What should I include in my class documentation header

I'm looking for informative class documentation format for my Entity, Business Logic and Data Access classes. I found following two formats from here Format 1 ...
1
vote
3answers
481 views

Commenting strategies in C# & asp.net web api

I've been working on a ASP.NET Web Api 2 project as a learning exercise, and I was wondering what the norm regarding commenting is. I use the Repository / Service Pattern, and everything is very much ...
12
votes
8answers
3k views

Why do most programming languages not nest block comments?

A few do, but not any of the popular ones as far as I know. Is there something bad about nesting comments? I plan to have block comments nest in the (small) language I'm working on, but I would like ...
2
votes
4answers
298 views

Is it normal needing time to understand code I wrote recently [closed]

By recently I mean some weeks ago. I am trying to continue a project I left 2 weeks ago and I need time to understand some functions I wrote (not copied from somewhere) and it takes me time. Normally ...
6
votes
2answers
301 views

What has research shown about the effectiveness of comments?

I have been arguing with a friend about the necessity of comments, and the efficiency of different comment styles. The argument ended quite fast, as we could not find any research - or essay - that ...