Skip to main content
161 votes
Accepted

What's the phone number equivalent of example.org?

The North American Numbering Plan reserves 555-01 numbers for fictitious purposes. If you want an example Seattle number, for example, +1 206 555 0100 - +1 206 555 0199 would do. In the United Kingdom,...
Frank Shearar's user avatar
144 votes
Accepted

Name of a program's startup/initial loading window?

Those are usually called Splash Screens. A splash screen is a graphical control element consisting of window containing an image, a logo and the current version of the software. A splash screen ...
Tulains Córdova's user avatar
138 votes
Accepted

Should generated documentation be stored in a Git repository?

Absent any specific need, any file that can be built, recreated, constructed, or generated from build tools using other files checked into version control should not be checked in. When the file is ...
1201ProgramAlarm's user avatar
94 votes

Should a rookie hint be mentioned in the documentation or not?

Code reviews by people who are less familiar with the project are extremely valuable precisely because they discover such issues. “Well, obviously you need to do this and that first” says the ...
amon's user avatar
  • 134k
90 votes
Accepted

Should a rookie hint be mentioned in the documentation or not?

If you think of this from a business perspective: the more time developers (whether they are new or experienced) need to find things out, the more expensive it is for the client. So: The more ...
Jesper's user avatar
  • 2,579
57 votes

How do I document my code for minimum time review?

IMO the best documentation is the documentation you don't actually need. I also hate writing documentation and comments. With that being said: Pick readable and talking names. Don't use n, but ...
Mario's user avatar
  • 1,499
54 votes

Literate programming vs reasonably documenting your code

Literate programming is the nice idea that you can write your code together with an explanation or walkthrough of that code. Importantly, you are not constrained by the syntax of the underlying ...
amon's user avatar
  • 134k
52 votes

Is documenting a big project with UML Diagrams needed, good to have or even not possible?

Tldr Documentation should not be seen as something that you simply start doing. It carries a colossal business cost to maintain. It will require additional staff and skills in its own right. Long read ...
Steve's user avatar
  • 8,803
50 votes

Why and how to write clear code comments and when will documentations be needed beyond code commenting?

If the proofs are written badly or unclear, we usually go ask someone or the proof author for clarifications. in the case of programming, should programmers be able to read and understand a program's ...
Bart van Ingen Schenau's user avatar
45 votes
Accepted

Release first or document first?

Simple: Release a beta version! Then when documentation is done, do final release of the new version. If you have users willing to try out the new stuff, then by all means take advantage of that. You ...
hyde's user avatar
  • 3,754
42 votes
Accepted

What are better ways of indicating "insert actual value in place of the placeholder value" in documentation?

The standard way to deal with a certain part of text that needs to stand out from other parts of text is through typographic means: using italics, boldface, size, capitalization, color, different font ...
Jörg W Mittag's user avatar
40 votes

What's the phone number equivalent of example.org?

An oft-used example phone number is the numeric progression. (123) 456-7890 It's widely understood that this doesn't mean you should call that number -- it's an example. Additionally, according ...
Cullub's user avatar
  • 525
35 votes

Should a rookie hint be mentioned in the documentation or not?

I'll take a different stance here. You write: A friend later told me to add build: . and remove image: docker.git... from the docker-compose.yml. This fixed it. I apologize if I misinterpret what ...
Heinzi's user avatar
  • 9,758
30 votes

The Don't Repeat Yourself (DRY) principle in documentation

About this specific problem: From a technical perspective for me, the documentation of Array.copyOf is DRY, from my Developer perspective it is not. The relevant information of each method are the ...
JanRecker's user avatar
  • 1,576
27 votes

How do I document my code for minimum time review?

Treat your code as documentation Your code is your primary documentation. It precisely describes what the resultant app, library or whatever, actually does. As such, any attempts at speed up the ...
David Arno's user avatar
  • 39.3k
27 votes

Literate programming vs reasonably documenting your code

Literate programming is great in situations where the code is mostly there in support of the prose. That's why Jupyter notebooks and similar are common for scientific programming. I also use it when I ...
Karl Bielefeldt's user avatar
27 votes
Accepted

When to add version numbers to documentation

This depends on how you plan which features go into which release. For example, if any feature that is merged during a certain timeframe will make it into the 2.4 release, then you can use that ...
amon's user avatar
  • 134k
26 votes

What is an effective way to record rationales behind product design decisions?

You record rationales behind design decisions by writing them down. Ideally nearby the item which is subject to the decision (which is not a "user story" - user stories are descriptions what has to be ...
Doc Brown's user avatar
  • 208k
26 votes

Why and how to write clear code comments and when will documentations be needed beyond code commenting?

There's two types of code documentation: documenting the interface, and documenting the code itself. One is for people who use your functions, one is for people who maintain your functions. When ...
Schwern's user avatar
  • 1,195
25 votes

Should generated documentation be stored in a Git repository?

My rule is that when I clone a repository and press a “build” button, then, after a while, everything is built. To achieve this for your generated documentation, you have two choices: either someone ...
gnasher729's user avatar
  • 45.4k
23 votes

Why and how to write clear code comments and when will documentations be needed beyond code commenting?

A lot of your question is more of a rant than an actual question but I am somewhat sympathetic. In my decades of experience with development, I have found documentation that is useful but I've also ...
JimmyJames's user avatar
  • 27.3k
20 votes

The Don't Repeat Yourself (DRY) principle in documentation

Lets start with the copyOf example: Is the second way compliant with the DRY principle? No, it is not. The similarities between these methods and their intended behaviour are way too obvious to ...
Doc Brown's user avatar
  • 208k
20 votes

Should a rookie hint be mentioned in the documentation or not?

Remember I can read faster than you can write. Unless you belabor the point or cause distracting confusion I can easily skip over what I find obvious. When documenting a project the worst people to ...
candied_orange's user avatar
20 votes

What are better ways of indicating "insert actual value in place of the placeholder value" in documentation?

I fully support Jörg's answer and recommend the usage of <var> elements with appropriate styling. However, to prevent the mistake of copying the square brackets and writing an array literal, you ...
Bergi's user avatar
  • 1,333
19 votes

Is documenting a big project with UML Diagrams needed, good to have or even not possible?

Reframing the question Indeed, managing documentation is costly. But the bigger the project, the more people involved and the longer the system's lifetime. If you count the time that it takes for ...
Christophe's user avatar
  • 77.3k
18 votes
Accepted

Best practice to mark a method that is called via reflection?

A combination of the suggested solutions: Use XML Documentation tags to document that the constructor/method is called via reflection. This should clarify the intended usage to colleagues (and my ...
Kasper van den Berg's user avatar
18 votes
Accepted

How to document alternative code I considered but didn't go with due to performance?

It is not bad practice to put this as a comment in code. Your goal is not to show everyone you did your homework, you want to prevent any successor to go "this is silly, I can do this more ...
Martin Maat's user avatar
  • 18.4k
17 votes
Accepted

How should I handle docstrings of subclass methods?

From PEP 257: The docstring for a class should summarize its behavior and list the public methods and instance variables. If the class is intended to be subclassed, and has an additional interface ...
enderland's user avatar
  • 12.1k
17 votes

Documenting design decisions in code comments?

I would argue it depends on the scope of your description. If your design decision is so granular that it's fully implemented in a single method, then a comment next to that method would be ...
Dan Pichelman's user avatar
17 votes
Accepted

Can creating a Software Design Document after development be justified?

In IEEE Std 1016 Section 3.1 Software design in context, you can find this paragraph: An SDD can be prepared and used in a variety of design situations. Typically, an SDD is prepared to support ...
Thomas Owens's user avatar
  • 82.7k

Only top scored, non community-wiki answers of a minimum length are eligible