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.

learn more… | top users | synonyms

195
votes
16answers
34k 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 ...
155
votes
50answers
14k views

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 ...
96
votes
10answers
7k views

How to make a large codebase easier to understand for new programmers

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 ...
92
votes
12answers
7k views

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 ...
75
votes
13answers
4k views

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

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 ...
69
votes
14answers
8k views

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 ...
68
votes
17answers
14k 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 ...
67
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()); ...
66
votes
15answers
9k views

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

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 ...
54
votes
17answers
4k views

How to deal with tautology in comments? [closed]

Sometimes I find myself in situations when the part of code that I am writing is (or seems to be) so self-evident that its name would be basically repeated as a comment: class Example { /// <...
51
votes
12answers
9k views

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

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 ...
45
votes
20answers
5k views

Should you write good documentation and clean code to increase the “Bus Factor”?

One of the main goals of software development companies is to increase their Bus factor This is also advocated in a talk that was organized by Google. That means that you should code and document ...
44
votes
14answers
3k views

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'...
42
votes
7answers
3k views

How do you keep track of what classes and functions your team has written?

When working on code, I face many of the same challenges that my teammates do, and I have written some helpful functions and classes, and so have they. If there is good communication, I'll hear about ...
41
votes
6answers
2k views

“I”, “We”, or Neither in code documentation

I find myself writing (hopefully) helpful comments in code (C++) documentation of the type: The reason we are doing this is... The reason I use "we" instead of "I" is because I do a lot of academic ...
40
votes
8answers
6k views

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 ...
39
votes
12answers
2k views

Documentation in OOP should avoid specifying whether or not a “getter” performs any computation?

My school's CS program avoids any mention of object oriented programming, so I've been doing some reading on my own to supplement it -- specifically, Object Oriented Software Construction by Bertrand ...
38
votes
6answers
2k views

What should I do to leave a job professionally? [duplicate]

Given that the current employer knows and has been given appropriate notice ahead of time, how can a programmer make a clean job transition from his old job? What things should the programer consider? ...
35
votes
9answers
2k views

Can non-IT people handle a wiki? [closed]

My company is looking to improve their market research data management. Current data management style: "Hey Jimbo, where's that picture of our WhatZit 2.0? "yeah I remember that email about that ...
33
votes
3answers
2k views

What roadblocks face the development process in using plain-text markup languages as opposed to, e.g., Microsoft Word? [closed]

I'm currently an intern at a government contractor and am getting the (obnoxiously unavoidable) feeling that Word is the de-facto standard in the software development process. Its binary format makes ...
30
votes
3answers
1k views

Origin of “Readme”

When did people start writing Readme files? It seems that pretty much all programs have this file, regardless of the format. Is there any documented first use of this document?
27
votes
6answers
3k views

Methodology for documenting existing code base

I work as part of a team on an existing application that has no inline documentation, nor does it have technical documentation. As I've been working on various bug reports on the application, I've ...
24
votes
11answers
2k views

When do you start documenting the code? [closed]

Some friends and I recently started a medium-size project. We already covered the design part (at least the first attempt) and now we are moving into coding. We already have implemented some objects ...
23
votes
7answers
3k views

Release first or document first?

I've been working on a project for a couple years now, and I'm starting to gather a decent user base. I've created a project page with some basic documentation, but it's really not much more than a ...
23
votes
1answer
2k views

Why does the documentation on some languages say “equivalent to” rather than “is”?

Why does the documentation on some languages say "equivalent to" rather than "is"? For example, the Python Docs say itertools.chain(*iterables) ... Equivalent to: def chain(*iterables):...
23
votes
4answers
1k views

Is BDD actually writable by non-programmers?

Behavior-Driven Development with its emblematic “Given-When-Then” scenarios syntax has lately been quite hyped for its possible uses as a boundary object for software functionality assessment. I ...
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 ...
21
votes
5answers
1k views

How-to convince company to start documenting for legacy software [duplicate]

It has been less than a year since I joined my current company. Their majority of sales have come from a single product that has been alive since the last 10 years. However, there is minimal (if at ...
20
votes
5answers
15k views

Design documents as part of Agile

At my workplace, we face a challenge in that "agile" too often has meant "vague requirements, bad acceptance criteria, good luck!" We're trying to address that, as a general improvement effort. So, ...
20
votes
6answers
8k views

Git-friendly spreadsheet format? [closed]

We're trying to move our project documentation process from Google Documents to a set of self-hosted Git repositories. Text documents are Git-friendly enough, since we usually do not need any fancy ...
19
votes
4answers
2k views

Documenting mathematical logic in code

Sometimes, although not often, I have to include math logic in my code. The concepts used are mostly very simple, but the resulting code is not - a lot of variables with unclear purpose, and some ...
19
votes
12answers
1k views

What makes documentation good? [duplicate]

I need to write documentation for several projects I worked on. I was wondering what, according to your experience, makes documentation useful and complete. What part should I include, how deep should ...
19
votes
6answers
2k views

Old programmer disappeared. About to hire another programmer. How do I approach this? [closed]

After spending over one year working on a social network project for me using WordPress and BuddyPress, my programmer has disappeared, even though he got paid every single week, for the whole period. ...
19
votes
8answers
1k views

Should you document everything or just most?

It seems a bit of a controversial subject to document everything, including the "JavaBean" syntax of getters and setters for fields: People say its needlessly long and repetitive breaking DRY (don't ...
18
votes
4answers
5k views

How to document the high-level structure of a Java program?

Background: My collaborators and I are writing an article for an academic journal. In the course of our research, we wrote a simulation program in Java. We want to make the simulation program freely ...
18
votes
1answer
1k views

When systems get larger and larger, how do you keep a global understanding of your system? [duplicate]

Today I realized painfully that for some decisions you need a good overall understanding of the system. Otherwise, the risk is too high that your assumption turn out to be wrong. Imagine that you are ...
18
votes
5answers
5k views

What grammatical tense should I write my specifications in?

We are currently writing functional and technical specifications in a two column format; summary sentence and technical detail. The details often refer to an appendix with diagrams, layout designs ect....
17
votes
2answers
8k views

What standard superseded 830-1998?

I have been looking into how to document software projects more formally, and I have learned about IEEE 830-1998: Recommended Practice for Software Requirements Specifications. However, as you can ...
16
votes
5answers
8k views

What does your Technical Documentation look like? [duplicate]

I'm working on a large project and I would like to put together some technical documentation for other members of the team and for new programmers joining the project. What sort of documentation ...
15
votes
6answers
2k views

Can you claim that your product is fit for purpose when it uses OSS software which does not guarantee it?

I am working on a product for a client that must be valid and fit for purpose. It's built on a LAMP stack (PHP/Cake), so there's GPL, MIT, PHP, APACHE licenses: "AS IS" BASIS, WITHOUT WARRANTIES ...
15
votes
6answers
686 views

Is saying “JSON Object” redundant?

If JSON stands for JavaScript Object Notation, then when you say JSON object, aren't you really saying "JavaScript Object Notation Object"? Would saying "JSON string" be more correct? Or would it be ...
15
votes
5answers
11k views

Writing a Software Requirement Specification

I have a few questions about writing a specification and they are: When we write a software specification, under the topic "User requirements definition" we have to specify the "Functions" and "...
15
votes
6answers
1k views

Are unit tests really used as documentation?

I cannot count the number of times I read statements in the vein of 'unit tests are a very important source of documentation of the code under test'. I do not deny they are true. But personally I ...
15
votes
7answers
8k views

Are wikis really appropriate to store documents for software development? [closed]

Everybody knows that well-documented software development leads to success. However, it usually means that not only plain text but also binary content will be involved in the document, such as a UML ...
15
votes
8answers
1k views

What are technical writing principles? [duplicate]

As a programmer, technical writing is an important skill to me. I get a lot of fun from it. I also learned from some good technical articles and books. What I need are technical writing principles or ...
15
votes
5answers
2k views

How do I go about writing a programming language specification?

I really enjoy programming language design. Sometimes I think my language projects and their potential users would benefit from a comprehensive standards document. I've looked at many language ...
15
votes
5answers
8k views

How are minimum system requirements determined?

We've all seen countless examples of software that ships with "minimum system requirements" like the following: Windows XP/Vista/7 1GB RAM 200 MB Storage How are these generally determined? ...
15
votes
7answers
2k views

How can Scrum be adapted to an academic environment?

I'm currently working with a professor at my university to develop new curricula for the Software Engineering and Capstone Design courses offered in my college. Up until recently, both courses used ...
14
votes
11answers
1k views

What should you leave behind for your successors?

Assume that you're a sole developer leaving a job. What kind of information/material, outside of the code itself, should you create and leave behind for your replacement? An obvious answer is "...
14
votes
6answers
3k views

Self-documenting code vs Javadocs?

Recently I've been working on refactoring parts of the code base I'm currently dealing with - not only to understand it better myself, but also to make it easier for others who are working on the code....