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

-2
votes
0answers
55 views

Reading Code Documentation [closed]

I have been studying computer science for a year and a half, and even after 5 programming classes plus my own studies I have yet to understand how does one go about reading source code on github ...
22
votes
6answers
2k 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
136 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 ...
2
votes
0answers
73 views

Best practice for documenting ports/hardware for embedded project? [migrated]

I've recently taken an interest in embedded development and am wondering how most people document their projects. For example: Each pin on PORTE is wired to an LED and is aliased as LEDPORT. ...
94
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 ...
6
votes
2answers
187 views

Is there something peculiar to Matlab or Mathworks that supports so much “undocumented” code?

I've been drilling into a lot of Matlab recently trying to interface with an in house algorithm engineer's work to modularize it for use in a test bench outside his suite of applications. I've come ...
0
votes
0answers
35 views

Is listing Types in documentation a code smell

I'm documenting a ruby application and looking closely at YARD. I like the increased structure provided over RDoc, but I'm unsure about the Type declaration. In YARD, you can do something like ...
2
votes
1answer
78 views

How to write proper documentation for references in a docblock? [closed]

I am adding documentation to PHP code using the phpDocs tool: /** * This is a summary * * This is a description * * @use This function is called here and here */ function doSomething(){ } I am ...
1
vote
1answer
42 views

What information should go into file-level document block?

I primarily develop for Node.js. I got into a habit of putting a file-level docblock into all of my .js files. It looks something like this: /** * project-name * * Licensed under the BSD-3-Clause ...
4
votes
3answers
101 views

When should “should” be used in documentation? [duplicate]

I was just reading http://lasagne.readthedocs.org/en/latest/modules/layers.html and wondering about some documentation style questions. One of them was the use of the word "should". For example: ...
0
votes
0answers
108 views

Interactive help in a statically-typed language with overloading

One of the nice features of IPython is that I can inspect a function. In [1]: def inc(x): ...: """Increments a number""" ...: return x+1 ...: In [2]: inc? Type: function ...
5
votes
4answers
152 views

What Type of Report or Documentation to Expect from my Programmers

First, I am not a programmer nor do I have any programming experience. I am an entrepreneur that had a website idea and hired programmers to custom build it. It has been going on for the last one year ...
1
vote
1answer
70 views

Documenting MVC JSON API

I've got an MVC5 application that we're using an a JSON API for various clients (mobile apps, other web applications, etc.) as well as a traditional web application. Controller actions that return ...
2
votes
2answers
159 views

Agile Scrum - Importance of requirement gathering and documentation and suggestions to improve

We are using agile scrum methodologies for developing and maintaining a product. Since we are a product company, we do not work with customer directly on day to day basis, but instead communicate with ...
1
vote
1answer
151 views

How can I find what Resources a Java EE container provides?

How can I find what "Resources" a Java EE container provides? Can I discover this programmatically, or is there documentation I should refer to? (Note that the Java EE tutorial is vague on this ...
0
votes
3answers
1k views

Who should write the Technical Design Document? The BA or the Developer? [closed]

I work as a Snr. BA in a large Manufacturing company and I've just implemented a new Requirements Management Process. We have a large range of internal developers who in the past have never been ...
2
votes
1answer
347 views

How do tools facilitate writing functional specifications?

C2 wiki on functional specifications suggest that this can be facilitated by tools, how? A Functional Specification is a list of demands and constraints intended to describe a product to be ...
2
votes
3answers
175 views

Documenting intent Vs knowledge

It is said you should document the intent of your function or class which I agree with. However recently this line became a little bit blurred when I was wanting someone to document why this ...
4
votes
1answer
89 views

What is the origin of the phrase “extirpated as a potential munition”

I recently came across this statement in the Perl documentation: extirpated as a potential munition derived from the sentence: "Creates a digest string exactly like the crypt(3) function in the ...
1
vote
3answers
261 views

Should code comments explain the control flow?

Should comments explain how the application control flow works? For example, the relationships between classes, how this function is used by other functions, and what we are trying to do with these ...
3
votes
1answer
258 views

How do I write a REStful API's functional specifications?

I've been looking for answers about writing functional specifications for a software for a while now but I can't seem to find an answer to my specific case. I think I understand the difference ...
1
vote
0answers
100 views

UML diagram for SSIS process

I'm trying to do some technical documentation and would like to include some diagrams to better explain the processes in the system. The process I'm currently trying to describe is the following: ...
-2
votes
3answers
140 views

Affecting culture as a newly hired developer [closed]

I've been in my first professional position for about six months now, and so I am hitting what I suppose is the pretty typical moment: Naievely perhaps, I think there's a lot of cultural baggage ...
4
votes
2answers
951 views

How should I annotate, that a class is immutable in Java?

I recently stumbled upon how useful immutable objects are and that e.g. if you pass elements to a constructor and your class should be immutable, you have to copy these elements if they are not ...
1
vote
1answer
75 views

Documentation of interfaces

I know how to document a function: /** * Prints a greet message to the web page */ function greet() { echo "Hi!"; } Or describe the usage of a variable: /** * @type string $name The user's ...
5
votes
2answers
122 views

peer review code documentation [closed]

We all know that code reviews are generally a good practice, but what about reviewing documentation? Many devs that I work with will put up wiki pages, javadocs, etc, but most of the time, unless ...
0
votes
3answers
85 views

Defining resource allocation in method documentation

I want to write a library with "no resource leak guarantee" feature. So I shall know whether each method allocates any resource or not. It may change the code. For example: void foo() { ...
3
votes
3answers
178 views

Is it misleading to label code as a particular design pattern if it only loosely fits the definition?

Background: I have a rough, but working understanding of ~15 design patterns. It's been my experience using design patterns in my own projects that the resulting implementations usually end up as some ...
3
votes
1answer
181 views

Usage of this keyword in constructor chaining?

I am reading msdn documentation for this keyword. They gave three usages for this keyword as follows To qualify members hidden by similar names To pass an object as a parameter to other methods To ...
4
votes
1answer
395 views

How to move php documentation closer to standards?

I have an large php project. I used to document it with NaturalDocs, but I didn't include the documentation generation in the build process for a long time ( years ). I recently started using ...
0
votes
2answers
157 views

The source is the documentation - part 1 [closed]

Searching the specification for the btrfs file system i stumbled once more over the catchphrase: "The code is the documentation". This implies that changing the code changes the specification. Does ...
1
vote
1answer
227 views

How to make Doxygen documentation that helps in understanding the code?

So a few years ago I came across a statement that most of the Doxygen generated documentation out there is quite bad. "Bad" in the sense that defies the purpose of documentation and doesn't help in ...
0
votes
3answers
153 views

Seeking advice writing functional requirements [duplicate]

I inherited a project that I've been maintaining for approximately a year now. The project primarily revolves around performing various financial calculations for the end user. It's roughly 100,000 ...
1
vote
0answers
117 views

Is this synchronization required in service onCreate method?

Below is a sample code i captured from android doc Per service instance onCreate will be called only once. Ref: here and here The synchronization and singleton doesn't make any sense to me in this ...
1
vote
1answer
158 views

Does phpDocumentor tags order matter?

When we document our class, method and/or function with phpDocumentor, is there any specific order I should follow according to the standards? I know it doesn't matter for output the document. Since ...
46
votes
12answers
7k 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 ...
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 ...
187
votes
16answers
31k 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 ...
1
vote
1answer
169 views

Changelog Management [closed]

I'm currently developing a WinForm application. In order to inform the client about the improvements and corrections made during the last version, I would like to manage and display a changelog. I ...
10
votes
1answer
231 views

Implied precision of floating-point functions

While reviewing another programmer's implementation of a function to calculate the normal distribution CDF, I made a suggestion to either replace the entire implementation with Python's built-in ...
3
votes
1answer
417 views

When to declare @throws with a Scala annotation - abstract parent or concrete implementation?

In this StackOverflow question I asked about the behavior of the @throws annotation in Scala. Now that I understand how it works I want to ask about best practices with using it. Here's a repost of my ...
1
vote
0answers
31 views

New project from a third party and documentation [duplicate]

I'm going to become the custodian of an iOS project developed by a third party and my boss just asked me for a list of documentation that I think we should be asking the third party for when they hand ...
90
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 ...
0
votes
2answers
146 views

Referencing StackOverflow questions in comments [duplicate]

Often when coding I'll get stuck on a particularly tricky problem and will go about searching for a solution. More often than not this leads me to a StackOverflow question that provides a full or ...
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
99 views

How specific should be an interface about its implementation details?

Perhaps I should have picked a better title, but anyway... Basically what to do with two or more implementations that have the same public interface, but they are meant for slightly different ...
0
votes
1answer
59 views

Referencing official documentation in source-code documentation

What are your preferences for referencing official documentation (like a white paper) for an algorithm from comments in the code that implements it? I'm trying to decide between two methods, as ...
5
votes
2answers
2k views

How to do documentation for code and why is software (often) poorly documented?

There are some good examples of well-documented code out there, such as java api. But, a lot of code in public projects such as git and internal projects of companies is poorly documented and not very ...
2
votes
5answers
207 views

How viable is to create a mini documentation inside the source code

So, I work as a developer. We are a small team. The majority of the people (everyone except the project manager and the senior developer) are still in university. We have very flexible work hours, ...
3
votes
2answers
201 views

Is it customary for software companies to forbid code authors from taking credit for their work? do code authors have a say?

The company I work for has decided that the source code for a set of tools they make available to customers is also going to be made available to those customers. Since I am the author of that source ...