Questions tagged [comments]

Questions about writing comments in code.

Filter by
Sorted by
Tagged with
2
votes
3answers
224 views

Versioning a function/method

While this might seem more like a piece of an easy task to others, it's honestly not easy for me. At this stage, I find myself wandering how best to version my functions/methods. What does this mean? ...
0
votes
3answers
149 views

Is it good practice to put comment headers into each file?

I have an Unity project with countless of C# script files and I'm working on it solely. Although nobody else is working on it, I'm aware that some form of code documentation is crucial for my future ...
48
votes
6answers
12k views

Is a comment aligned with the element being commented a good practice?

I am a home, amateur developer for 25 years and I just had a bright idea regarding comments. Like all such novel bright ideas, someone has probably already done it and there is probably a consensus on ...
2
votes
1answer
132 views

Are there established approaches to providing informal proofs of properties a function or system has?

I have asked about the more nebulous 'system' and functions in general, but to explain my question let me just consider a pure function. I think of pure functions as lemma/theorems/what have you. ...
4
votes
5answers
216 views

Approaches for comment duplication

For code, we know approaches like DRY and we tend to extract common functionality. What approaches are recommended for comments? Perhaps it's a really open question, so I'm going to go with my ...
0
votes
2answers
120 views

Should I declare motivation when commenting? [duplicate]

When commenting code, which of the two approaches considered good practice? Explain the content of the code, "translate" it to human - readable language, but not provide any explanation ...
3
votes
5answers
218 views

Dealing with unwanted usages of a function

I am writing a function that I would not like to get called given a certain context and am wondering how best to convey that to possible users of the function. Assume, for exemplification, I am ...
1
vote
0answers
44 views

What to put in which kind of comment in ClearCase?

I'm used to comments in Git and Mercurial repositories: Commit comments, which may involve multiple files over the whole repository - has a comment. Commits without comments are possible, but rare (...
67
votes
13answers
17k views

How to avoid comments about one line of code for cleanliness

I'm trying to clean up some of my code using some best practices, and read that comments are almost always a bad idea for future maintainability. I've managed to get rid of most of them by refactoring ...
39
votes
9answers
8k views

Is there a method for differentiating informative comments from commented out code?

Throughout the course of programming, you will end up with some comments that explain code and some comments that are removing code: // A concise description const a = Boolean(obj); //b = false; Is ...
2
votes
3answers
1k views

How to deal with long URLs in comments that exceed the 80 characters limit?

I generally try to adhere to the 80 character limit for each line of code to satisfy my colleagues, to satisfy the linting tools, and to maintain an image of professionalism when random people look at ...
1
vote
2answers
263 views

Python method docstring: to use or not to use Args: Returns:

Default docstring from PyCharm automatically creates template with Args: and Returns: sections. However I have observed that this prompts people to say obvious things, frequently just stating the ...
3
votes
1answer
173 views

How should I document a method's computational complexity in the code?

I am currently working on a project that has very little documentation overall. The team is working to change that. I am doing my part, by adding xml comments to the methods I make and the ones I edit,...
9
votes
1answer
899 views

What does “TILT” mean in a comment?

I'm reading Clean Code by Robert C. Martin, and the phrase TILT inexplicably appears in some code samples. Example (it's in Java, by the way): ... public String errorMessage() { switch (...
2
votes
1answer
92 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
344 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) ...
28
votes
6answers
10k 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
675 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
1answer
712 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
123 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?
4
votes
3answers
2k 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 ...
6
votes
5answers
1k 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 ...
4
votes
3answers
2k 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 ...
99
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 ...
9
votes
5answers
952 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....
12
votes
3answers
2k 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
447 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 ...
3
votes
2answers
1k 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
169 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
87 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
284 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
949 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
58 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 ...
6
votes
1answer
1k 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
438 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
79 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
1k 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
158 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
5k 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
651 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.
0
votes
6answers
235 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 ...
148
votes
17answers
40k 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 ...
13
votes
1answer
349 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(...
8
votes
3answers
2k 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
1k 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 ...
3
votes
2answers
203 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
5k 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
508 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
985 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 ...