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

162
votes
15answers
27k 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 ...
88
votes
12answers
6k 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 ...
70
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 ...
66
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 ...
64
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 ...
61
votes
16answers
6k views

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

How to deal with tautology in comments?

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 { /// ...
45
votes
20answers
4k 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
12answers
6k 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 ...
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 ...
40
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 ...
38
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 ...
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? ...
37
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 ...
37
votes
18answers
2k views

How can I improve my technical writing?

Writing documentation is part of programming, and writing well is part of what makes the documentation useful. So, what are some hints or guidelines for good writing in the technical realm? What are ...
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?
29
votes
8answers
3k 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 ...
23
votes
3answers
17k views

What javadoc equivalents do you use in .net? [closed]

Java developers use Javadoc in order to write inline documentation in their comments. What are the alternatives for .net - specifically c# and VB.net that people actually use in real world projects?
22
votes
13answers
2k views

When do you start documenting the code?

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 ...
21
votes
4answers
995 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 ...
21
votes
6answers
2k 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 ...
20
votes
5answers
919 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 ...
19
votes
12answers
864 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
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 ...
17
votes
4answers
2k 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 ...
15
votes
6answers
1k 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
4answers
950 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 ...
15
votes
6answers
512 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
8answers
747 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
5k 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
7answers
964 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
5answers
1k views

Is a well written documentation a good enough reason for learning a programming language?

I am learning Python currently which wasn't part of my college curriculum. I was asked in an interview why I chose Python and I replied that it is easy to learn and the documentation is very well ...
14
votes
2answers
5k 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 ...
14
votes
6answers
4k 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 ...
14
votes
5answers
4k 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? ...
13
votes
11answers
1k views

Does searching documentation and samples look bad? [duplicate]

I am starting a new job in a company with many developers and media people, the layout of the place is open with computers around a skinny oval, I have worked in small teams and programming embedded ...
13
votes
6answers
527 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 ...
13
votes
5answers
13k views

Fastest way to document software architecture and design [closed]

We are a small team of 5 developers and I'm looking for some great advices about how to document the software architecture and design. I'm going for the sweet spot, where the time invested pays off. I ...
13
votes
5answers
8k 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, ...
12
votes
6answers
2k 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 ...
12
votes
6answers
829 views

Why do so many libraries have no/poor documentation?

In a similar vein as the Why do many open source projects have no documentation about their design or architecture? question, I'm curious: Why are so many libraries so lacking in end user ...
12
votes
9answers
792 views

Code Documentation First?

Has anyone ever tried creating a complete code documentation first, before actually writing the code? I was thinking about this earlier because I thought it would help to write a concrete interface ...
12
votes
5answers
1k views

Do you create a design with UML before you start? [duplicate]

Possible Duplicate: How often do you use Formal UML? I'm currently following a study UML called UML Fundamentals. While studying, I wondered if companies even bother creating system ...
12
votes
4answers
276 views

Are there efforts to build a collaboratively edited HTML/JS/DOM reference?

W3Schools has a reputation of being incomplete, sometimes incorrect, and ridden with advertising; still, when looking to look up some things or link to documentation when answering a SO question, it ...
12
votes
5answers
2k views

What are the deliverables to give to the client for a web application ?

I have completed a web application which is basically developed in PHP and is just another regular web application. Usually when I deliver the final production release I just handover the code ...
12
votes
7answers
845 views

Should a design document contain a discussion of the pros/cons to a given design or should it focus on facts and rationale?

I'm currently in the process of updating a design document so that it is correct and up-to-date for future developers. Currently, the document focuses on only the facts, presenting how the design is. ...