Questions tagged [documentation]

Software documentation is written text that accompanies computer software. It explains how the software operates, how to install it, how to use it, and other resources for help.

Software documentation is written text that accompanies computer software. It either explains how it operates or how to use it, and may mean different things to people in different roles.

The types of documentations are:

  1. Requirements: statements that identify attributes, capabilities, characteristics, or qualities of a system. This is the foundation for what shall be or has been implemented.
  2. Architecture/Design: an overview of the software. It includes relations to an environment and construction principles to be used in design of software components.
  3. Technical: documentation of the code, algorithms, interfaces, and APIs.
  4. End User: manuals and online help for the end-user, system administrators, and support staff.
  5. Marketing: how to market the product, style guides, and analysis of the market demand.

Documenting source code can be helpful for anyone who might be reusing that piece of code. Many IDEs support *doc comments, such as Javadoc and PHPdoc.

625 questions
250
votes
16 answers

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 my own words) often "comments are apologies for…
Aviv Cohn
  • 21,190
  • 31
  • 118
  • 178
154
votes
50 answers

My boss wants a narrated line-by-line English explanation of our code

I have been specifically asked to give line by line (or as appropriate - for example, image by image, etc.) explanation or commentary which my boss wants to be able to read and follow. Since he is not a programmer, he can not follow the code so…
Billy Moon
  • 329
  • 2
  • 5
  • 14
136
votes
3 answers

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

RFC 2606 standard reserves the domain names example.org, example.net and example.com for the purpose of being used as examples in documentation. What is an equivalent for a phone number (including country code) that can be used as an example, e.g.…
Florian
  • 1,089
  • 2
  • 8
  • 7
109
votes
10 answers

How to make a large codebase easier to understand

Suppose that I am developing a relatively large project. I have already documented all my classes and functions with Doxygen, however, I had an idea to put a "programmer's notes" on each source code file. The idea behind this is to explain in…
Alex Spataru
  • 1,257
  • 2
  • 8
  • 9
98
votes
17 answers

Do TODO comments make sense?

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 little piece of code //TODO translations This made me…
96
votes
13 answers

Should the commit history be used to convey critical information to developers?

During a meeting regarding the rollback of a third-party SDK from the latest version it was noted that the our developers already flagged in the commit history that the latest version should not be used. Some developers argued that this was a bad…
rjzii
  • 11,274
  • 6
  • 46
  • 71
89
votes
13 answers

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()); …
Alexis Dufrenoy
  • 1,310
  • 1
  • 11
  • 15
79
votes
13 answers

What are examples of comments that tell you why instead of how or what?

First of all, in this question I'd like to stay away from the polemic on whether source code commenting is good or bad. I'm just trying to understand more clearly what people mean when they talk about comments that tell you WHY, WHAT or HOW. We…
rick
  • 1,945
  • 2
  • 19
  • 16
74
votes
14 answers

How should I remember what I was doing and why on a project three months back?

I was working on a project three months back, and then suddenly another urgent project appeared and I was asked to shift my attention. Starting tomorrow, I'll be heading back to the old project. I realize that I do not remember what exactly I was…
Aquarius_Girl
  • 1,601
  • 2
  • 18
  • 25
67
votes
15 answers

I'm going to quit my job because of our platform: how can I leave a productive explanation of this?

I'm planning on leaving my current job because we're locked into using Blub, with an enterprise Blub framework and a Blub-level web server, on mediocre shared hosting. My coworkers are friendly and my boss is an average small business owner - I want…
Brighid McDonnell
  • 823
  • 1
  • 6
  • 8
66
votes
10 answers

Is there such a thing as having too many private functions/methods?

I understand the importance of well documented code. But I also understand the importance of self-documenting code. The easier it is to visually read a particular function, the faster we can move on during software maintenance. With that said, I…
Sal Rahman
  • 1,544
  • 1
  • 12
  • 22
62
votes
12 answers

Is there any logical reason to auto-generate code documentation?

Automatic documentation generation can be done with a variety of tools, GhostDoc being one of the more prominent. However, by definition, everything it generates is redundant. It takes a look at names of methods, classes, etc. and outputs English…
Jez
  • 1,308
  • 2
  • 10
  • 19
60
votes
8 answers

Should generated documentation be stored in a Git repository?

When you use tools like jsdocs, it generates static HTML files and its styles in your codebase based on the comments in your code. Should these files be checked into the Git repository or should they be ignored with .gitignore?
garbage collection
  • 1,281
  • 1
  • 13
  • 15
60
votes
3 answers

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

I am writing user documentation (an SOP) that involves third party programs that I am trying to describe well. One such program is a server that offers little indication of it's startup besides a graphic that shows during its initialization/startup…
rtmh
  • 643
  • 5
  • 8
60
votes
14 answers

What's with the aversion to documentation in the industry?

There seems to be an aversion to writing even the most basic documentation. Our project READMEs are relatively bare. There aren't even updated lists of dependencies in the docs. Is there something I'm unaware of in the industry that makes…
user7433
1
2 3
41 42