Stack Exchange Network

Stack Exchange network consists of 174 Q&A communities including Stack Overflow, the largest, most trusted online community for developers to learn, share their knowledge, and build their careers.

Visit Stack Exchange

Questions tagged [comments]

Questions about writing comments in code.

0
votes
0answers
48 views

How can I count number of lines of comments? [closed]

I have a bunch of Matlab script/function files that I and the rest of my team need to work on. We have little to no idea what most of the files do, and little to no idea which ones belong together and ...
1
vote
0answers
62 views

/// <summary> comments without the bloat [closed]

I like the documenting feature you get with /// comments, but hate the boilerplate. Is there a way to make visual studio just use whatever comment is above a class as the documentation, without ...
1
vote
1answer
66 views

Are file summary comments a good way of knowing what each file does?

I want to know if including a file summary comment at the beginning of each file is a good way of knowing what each file does or is there a better way.
2
votes
1answer
165 views

Alternative for commented out code that will be used later

I had to implement a module that after completed, the client suddenly asked that for a while it would not need to be displayed, so I was told to comment it out (since we probably will use it later) ...
18
votes
6answers
1k views

Why is it wrong to comment out code and then gradually remove it to keep track of what I've already done and what remains to be done?

Whenever I find out that a large portion of my code needs to be changed, either because it is incorrect or because it needs to be adapted to major architectural changes necessited by other reasons, ...
-1
votes
2answers
192 views

Is it good practice to add comments above generated fields?

Every time I let Eclipse generate a field (most often a serial version UID), it adds a comment above it. Example: /** * */ private static final long serialVersionUID = 6347144762354188381L; This ...
0
votes
0answers
136 views

Should I add XML comments in DTO models or entity models

I have 2 models, DTOs and database models (entities) that map to the database. I usually put XML comments above the properties to describe what are they for. class MyEntity { /// <summary> ...
1
vote
2answers
116 views

Links to documentation in comments? [duplicate]

I sometimes put a link to the site where I copied a chunk of code from in case I forget what it does. Is this a bad practice? Should I copy the explanation from the site instead of linking to it?
2
votes
3answers
205 views

How do you denote a variable in a comment?

Let's say I have the following function in Python: def foo(one, two): return one + two And I want to document it with "adds one to two". However, this is confusing, because I could just mean ...
5
votes
5answers
567 views

Documenting design decisions in code comments?

How can I best document a code design decision in my source code? Should I just add a massive comment at a point I feel is right? Or should I just create a separate file? This issue is important for ...
3
votes
3answers
356 views

Should //given //when and //then comments be included in unit tests?

I've joined a new team of great colleagues and a difference of opinion has come up concerning including //given //when and //then comment blocks in unit tests. For example public void ...
95
votes
12answers
16k views

My client wants 25% of comments in my current project, how to react? [closed]

junior developer here. I am currently working alone on a web application for a big client of my company. I started last month. The client wants at least 25% of comments in each of its software ...
8
votes
5answers
483 views

Is it generally helpful to include JIRA issues in code comments?

Once in a while, I leave comments like # We only need to use the following for V4 of the computation. # See APIPROJ-14 for details. or # We only need to use the following for V4 of the computation....
8
votes
3answers
241 views

Are docblock typehints redundant when using strict typing

I have a quite large private codebase which has evolved for about ten years now. I'm not using phpDocumentor but since using docblock sections has become quite the standard in open source projects I ...
4
votes
4answers
388 views

Which is better, one central detailed comment, or several smaller ones?

To restate the question: Which is better, one central detailed comment, or several smaller "sprinkles"? Bear with me while I set up the scene: I've got this function for popping a value from a queue ...
1
vote
2answers
304 views

Additional spacing before an inline comment [closed]

Early on in my career I was advised to add additional spacing between source code and an inline comment, like so: de_cologne = (i == 4711 # 1 and j == 1799) # 2 Note the two spaces. ...
1
vote
1answer
145 views

Are comments at the top of a source file a bad idea? [duplicate]

I use Xcode to edit my source files, and typically a file will look like this // // Queue.swift // SomeCompany // // Created by Someone (Job Title) on 26/06/2017. // Copyright © 2017 SomeCompany. ...
1
vote
1answer
77 views

Making control flow explicit through printing instead of using comments?

I would have the opinion and good practices in script programming about using print statements to materialize the control flow (I usually use an anchor mark, then the name of the function just entered,...
-2
votes
2answers
279 views

Is it ideal to put code comments in an official release?

I will release a program (not Alpha/Beta/Testing versions). Should I remove the comments in the code? I have some comments that I added to make the code less confusing to me, but since the program ...
2
votes
1answer
143 views

Describing JS program flow in @fileoverview

I have to edit other people's JavaScript code. The code usually loads some data from a Web API, generates a table, places it into the HTML page, and attaches some event handlers. Due to the async ...
0
votes
1answer
41 views

Should requirement/issue number/code be included in the comments of the source code? [duplicate]

I am working on a number of maintenance projects and I always include requirement/issue number/code in the the comments whenever I am adding or changing code. In such way I provide traceability from ...
3
votes
1answer
628 views

Style: line length and wrapping of comments in JavaScript [closed]

I'm fine with staying under 80 characters per line for code (even if some consider that limit outdated), but I'm split (no pun intended) when it comes to splitting comments over multiple lines, versus ...
5
votes
3answers
262 views

How to avoid falling into the trap of not commenting code? [duplicate]

I've been working on a project for about a month now. I am extremely familiar with the code and understand it to the extent where I feel that it is so easy to understand, that most methods don't need ...
51
votes
7answers
9k views

TODO comments with deadlines?

Background I'm working in a team that's looking to implement zero-downtime deployments. We're planning on using a blue/green deployment strategy in order to achieve this. One of the things I'm ...
1
vote
1answer
57 views

Should I doxygenate implementation files in a library of mine, in addition to the headers?

I'm in the process of writing Doxygen comments for this library of mine; it's a header-mostly C++ library, but it does have some code which gets linked rather than included. For that code, which has ....
4
votes
1answer
452 views

Abuse of XML comments to keep comments up-to-date (in C#)

Problem: Comments deteriorate when renaming a variable/class/method/etc in Visual Studio. Occurrences of said symbol in comments do not get updated by refactoring (no surprise, how could VS know). ...
4
votes
3answers
151 views

Is the following comment clear: “Until contested” [closed]

Suppose that you see the following pattern in code: function foo() { ... var someFlag = false; // Until contested for/while/if () { ... // Possibly deeply nested in some ...
1
vote
2answers
807 views

What is the difference (if any) between REM statements and comments?

I have recently come across the term REM statement and wondered, is it synonymous with comment?
-4
votes
2answers
319 views

What to do with old code? [duplicate]

Often I change code but I don't know if I might need the old one, I can leave it under comment but then I find myself with lots of green lines while I hardly can read the real code. Thanks.
2
votes
1answer
542 views

How to add multiline comments for field of the struct in Go? [closed]

I faced with need add big comment for one of field of my struct, but I don't how to make it more idiomatic and graceful. You can see my versions, but, I think, it's unpleasantly to see. Any ...
0
votes
5answers
185 views

Using HTML id or class instead of comments

I have two elements inside a container. I don't need to give the two inner elements any id or class since they require no CSS or JS references. Is giving them an id just for the purposes of ...
140
votes
17answers
29k views

Coding standard for clarity: comment every line of code?

I've worked in shops that produce life critical software and I've dealt with commenting rules that were meant to keep the code readable and potentially save lives. In my experience though the ...
12
votes
1answer
295 views

Introducing additional local variables as comment replacement

Is it good style to use additional, technically superfluous, local variables to describe what's happening? For example: bool easyUnderstandableIsTrue = (/* rather cryptic boolean expessions */); if(...
6
votes
3answers
609 views

“Comment everything the right way” and “Instead of writing comments, write more readable code.” - Both valid strategies?

When trying to learn about proper comment practices, I found a lot of conflicting opinions, and it's obviously a very subjective topic. So I'm not going to ask "Should I comment, or should I not?" ...
2
votes
3answers
484 views

Is there a way to comment a source file using a separate file?

I'm using a large and complex library including R and C++ code, available online via a subversion repository. Trying to figure out how it works I took a bunch of notes in the source code itself, in ...
4
votes
2answers
195 views

Distinguish different type of Comments

I would like to provide design decisions in the comments as well. I want design decision comments to be distinguishable from function contract comments, on cursory examination of source code. How to ...
6
votes
6answers
1k views

How much commenting is better for coding? [duplicate]

I don't have a formal computer science education, meaning that I did not study computer science topics in a university. However, I work at a programming job and write a reasonable amount of code. ...
4
votes
6answers
377 views

Should an Else statement be used just for a comment?

I came across the following in some sample code: if (urlStr) { NSImage *iconImage = [[NSWorkspace sharedWorkspace] iconForFile:urlStr]; node.nodeIcon = iconImage; } else { // it's a ...
1
vote
1answer
447 views

Does anybody still use TODO for writing code later on? [closed]

Statement I often find myself still writing the following statement all over my code: // TODO: (the work that needs done) I do this in order to flag that I need to come back and do something later ...
4
votes
5answers
7k views

Best way of writing comments in code [closed]

I was wondering how one should write comments in code. I mean, should a comment be a descriptive of what is done in code, like : //we have got array, now we iterate over it. code to iterate array or ...
2
votes
2answers
196 views

What's the noun for the result of an iteration?

I'm commenting some code right now, and I'm looking for a word meaning the thing being iterated over. Iterator is an object performing an iteration, but what's the object that the iterator is ...
0
votes
3answers
137 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 ...
31
votes
5answers
4k 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 ...
2
votes
4answers
145 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
107 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
141 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 ...
4
votes
2answers
1k 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
238 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
5k 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 ...
17
votes
6answers
2k 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 ...