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

0
votes
2answers
49 views

The best practice for writing of examples

I have written some projects. I try to annotate or comment all possible (hard to say if correctly toward clean explaining). I would like to write documentation for it, but I have problem with ...
3
votes
0answers
58 views

How much static analysis history should a company keep?

Supposing you work in a very large global company with lot of code at all levels (e.g. from embedded to mobile platform application code), and projects can last anything between 6 months to 5 years... ...
0
votes
1answer
58 views

Is there any common way to document libraries used in a Software Product? [closed]

One of our clients asked us for: Overview of the libraries we are using in a format which is common. List the libraries along with the licenses. The reason behind this requirement is: ...
5
votes
4answers
5k views

job handover checklist [duplicate]

I have resigned my old employer to start a new job, and I need to prepare a handover [documentation to be taken by some new employee that haven't arrived yet, and would be some weeks from when I go to ...
8
votes
4answers
27k views

What is an “implementation plan”? [closed]

I was recently given the task of creating an implementation plan document. When I asked for an example of one that I could look at, I was told to look at the Project Plan that had already been created ...
5
votes
1answer
52 views

How can I better document these data relationships/transformations?

I'm working on a project that uses RxJS to perform data transformations on varying sources of data, and I'm in the process of writing some documentation for it. I want to find an effective way to ...
21
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 ...
0
votes
5answers
1k views

Named output parameters vs return values

Which code is better: // C++ void handle_message(...some input parameters..., bool& wasHandled) void set_some_value(int newValue, int* oldValue = nullptr) // C# void handle_message(...some ...
4
votes
1answer
120 views

Set of specific values implementation vs. using some sort of generic set with advanced checks

I am working on a set implementation in JavaScript currently. This should kind of simulate generics as known from Java or C#. I need a mutable version of that (allows for adding/removing set values) ...
2
votes
7answers
1k views

Should you use “internal abbreviations” in code comments?

Should you use "internal abbreviations/slang" inside comments, that is, abbreviations and slang people outside the project could have trouble understanding, for instance, using something like //NYI ...
0
votes
1answer
101 views

Docstring convention for Python __str__, __unicode__, and __repr__ class methods

What is the docstring convention in Python for the following "magic" class methods: __str__ __unicode__ __repr__ Should I add docstrings for these? If yes, what should they say (for each)?
7
votes
1answer
186 views

How to document a Ubiquitous Language?

Our company is in the process of converting a lot of manual business processes (and the associated institutional knowledge) into new enterprise software. The project is going really well, but as we ...
68
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 ...
1
vote
2answers
106 views

Use a hash character or a dot when referring to methods and fields in software documentation? [closed]

Assuming I have this class (Java code only for the sake of example): class Person { private String name; public void setName(String name) { this.name = name; } } When I write ...
4
votes
6answers
431 views

Do you write Documentation in a language other than English?

A couple of months ago I moved to Germany. Taking some projects on my own, I've recently had the opportunity to develop with a company-based framework, that was very well documented, but in German. My ...
0
votes
3answers
2k views

Is there a difference between property and attribute?

These two words are completely synonymous for me, but I wonder if there's actually a useful semantic difference that I can incorporate into coding/naming conventions/process.
16
votes
2answers
7k 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 ...
15
votes
5answers
4k 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 ...
4
votes
4answers
10k views

Creating a coding standards document

I work in a control systems company, where the primary work is SCADA and PLC, along with other control systems stuff. Softwre development is not really something the company does, apart from little ...
66
votes
17answers
11k 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 ...
1
vote
1answer
82 views

How to document GUI screens transitions of a complex application

There is an application based on multiple screen model with pretty complex net of transitions between these screens. It has some similarities to a web page or Football Manager like games. Its main ...
2
votes
1answer
155 views

How do I represent a schema diagram of my MongoDB database?

I have a MongoDB database that I want to properly document its schema design. I know that MongoDB is a NoSQL database and is schemaless by nature, but I do enforce a schema through my application and ...
7
votes
6answers
1k views

How useful are function points? [closed]

How useful is it to measure function points? We use function points at my new job. I've heard of function points but haven't had any training or experience... but I don't have much confidence in ...
1
vote
3answers
172 views

Should I use future or present tense when writing a design spec document?

I'm writing a Design Specification Document for a college project and wondering about the tense I should use. The development on the project has not yet started, I'm just writing the UI design ...
0
votes
0answers
22 views

Organising client-server projects

I am about to spin up a new development in my shop. It will be our first client-server application. It will be written for .NET 4.6 using C# and visual studio. WCF will be used for interprocess ...
2
votes
2answers
98 views

Include internal defects into the release notes?

When delivering a product, Release notes clearly contain known issues found by customer in the previous build. But should we include defects that we, as a supplier, found during our testing, those ...
1
vote
0answers
47 views

Is there a good way to create an FAQ section within a markdown README.md [closed]

I have a small project where I want to put the FAQ into the main README.md page without having to fuss with manual formatting of it and ideally with collapsing sections to make it easy to scan the ...
0
votes
1answer
81 views

Should I document expected call-sequences when call-order matters?

In dynamically and weakly-typed languages*, I often find myself with structures like the following pseudocode: class Stateful: # [ various datamembers / attributes / properties / fields / etc. ] ...
6
votes
6answers
347 views

Hyperlinked, externalized source code documentation [closed]

Why do we still embed natural language descriptions of source code (i.e., the reason why a line of code was written) within the source code, rather than as a separate document? Given the expansive ...
1
vote
1answer
93 views

PHPDoc Comment, Class vs File

I am trying to standardise my code as much as possible, including DocComments, using PHPCS. It seems that the PEAR standards contain two sniffs that require almost exactly the same tags appear in the ...
8
votes
5answers
319 views

How to prevent changes to an internal API from breaking other projects?

We have like 20 - 30 independent modules/solutions. Each of these has about 7 - 10 projects with different classes, components, etc. These are all used internal to our company. Our problem is when ...
2
votes
1answer
91 views

How to generate learning material from your work [closed]

Catalyst: Recently my team has been tasked with bringing in house a large software project that has been worked on for over 20 years. Some of the old development team is still around, and originally ...
5
votes
5answers
628 views

Debug function input vs expecting code users to read the documentation - How far do I go? [duplicate]

I could write an endless amount of debugging code to handle the various components of input for a function, check that the correct data types are used, make sure things are decendants of the proper ...
2
votes
0answers
55 views

Standard for order of tags in PHP DocBlocks?

Based on the tags listed from this "standard", is there an order of the tags that people typically follow? Even if it's not something that has been entirely accepted, but something proposed? I am ...
1
vote
4answers
117 views

How to keep documentation up to date and accessible [duplicate]

The problem: Documentation is in code in the form of docs, its in wiki websites, its written down on notes, in diagrams and issue management systems. When documentation is so spread out, how does ...
10
votes
4answers
1k views

Why should comments / documentation of a JavaScript function include so much? [duplicate]

I was researching proper commenting practices for JavaScript and highly upvoted answer (+100) cites JSDoc-like commenting. JSDoc promotes comments like this: /** * Represents a book. * @constructor ...
1
vote
2answers
176 views

When is documentation, unit testing, QA and refactoring meant to be done in a 2 week agile sprint?

The team I am working on is trying to do agile development with 2 week sprints. I think we must be doing something wrong however, as we have to work like madmen to get the features implemented in the ...
3
votes
1answer
72 views

Methodology for exploring APIs in dynamic languages

As a regular user of Standard ML and, to a lesser extent, Haskell, the following pattern is deeply ingrained into my "instinctive" approach to navigating and learning new APIs: Understand the types. ...
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 ...
9
votes
1answer
163 views

How to keep code examples in javadocs up to date

I'm working on a small library that provides implementations of basic, well known string metrics. Mostly for my own education. So development happens whenever I've got a bit of spare time. Because of ...
95
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 ...
65
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()); ...
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 ...
8
votes
2answers
1k views

Documenting a programming language: Reference Manual

We are looking at revamping documentation across our product line. Part of that includes reference manuals for a programming language used as part of the system. When writing a reference manual for a ...
9
votes
4answers
3k views

Prepare source code handover plan [closed]

Our company is about to acquire a source code of a huge product. What are thing to take into consideration when the handover starts, to make sure we have everything and be capable to maintain that ...
9
votes
3answers
233 views

How to refer to specific areas of code in documentation?

I'm about to leave a project, and before I go my boss has asked for me to document code (I've not documented very well). It's not a big deal, the project is not terribly complex. But I'm finding ...
9
votes
4answers
489 views

Should we be looking out for lying code?

This is referring to a discussion in an answer and the comments of this question: What's with the aversion to documentation in the industry?. The answer claimed that "code can't lie" and thus ...
4
votes
3answers
165 views

Is there a difference between the quotes in `help',``help“, 'help' and ”help"?

Sometimes I find in the source code files comments have quotation marks like these ,notice the ` : `help' ``help" For example, these are comments from GNU cat source code file, cat.c: /* Plain ...
5
votes
3answers
634 views

How to document events?

Code documentation is usually related to a piece of code, be it small (method-level) or larger (class- or namespace-level). However, it is always about the inputs and the outputs of that piece of ...
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 ...