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.
3
votes
2answers
127 views
What's a good practice for taking notes when exploring a new codebase? [on hold]
I've started exploring 2 separate codebases, which I will be working on/with, almost at the same time. I'm worried things will get jumbled if I just try to remember them about both codebases, so I ...
2
votes
1answer
70 views
How to generate learning material from your work [on hold]
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
597 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
37 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
77 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 ...
-4
votes
3answers
89 views
Scrum vs Traditional waterfall documentation [closed]
Does scrum need documentation at all?
If so - What's the detail level it should have?
Is there a comparison between 'traditional' (waterfall?!) documentation vs scrum documentation?
9
votes
4answers
824 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
134 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
70 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
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
145 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 ...
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 ...
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 ...
64
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 ...
5
votes
6answers
308 views
Hyperlinked, externalized source code documentation
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 ...
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
231 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
486 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
561 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 ...
5
votes
1answer
461 views
Java code documentation in a separate docs file somehow mapped to a source file?
What would be a good alternative to inline Java documentation, i.e. can one have a separate docs file somehow mapped to a java source file?
I have never liked huge comment sections littered in code.
...
11
votes
5answers
2k views
Software Manager who makes developers do Project Management
I'm a software developer working in an embedded systems company.
We have a Project Manager, who takes care of the overall project schedule (including electrical, quality, software and manufacturing) ...
6
votes
2answers
200 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
37 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
84 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
46 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 ...
1
vote
1answer
79 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 ...
3
votes
3answers
294 views
How to be productive as an infrequent programmer? [closed]
My current day job is mostly project management and client liaison work, but I sometimes get involved in actual coding. I do this either because I have a clear vision of what I want the result to look ...
4
votes
3answers
106 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:
...
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 ...
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
...
4
votes
2answers
1k 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 ...
8
votes
3answers
2k views
How does one read RFCs and similar documents? [closed]
RFC:
Request for Comments (RFC) is a memorandum published by the Internet
Engineering Task Force (IETF) describing methods, behaviors, research,
or innovations applicable to the working of the ...
5
votes
4answers
159 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 ...
15
votes
7answers
1k 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 ...
7
votes
5answers
171 views
Do you have any team guidelines regarding exceptions? [closed]
My team recently inherited a project from a team where the amount of developers dropped so low they had to offload some work. One of the projects we inherited was a project littered with nested code, ...
2
votes
2answers
175 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
162 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 ...
5
votes
5answers
289 views
Should documentation be a company policy or every programmer's responsibility? [closed]
I have been struggling lately with the whole subject of documentation at my current position. I am at a point in my programming career in which I feel I have just been birthed into the whole world of ...
5
votes
2answers
46k views
What is the difference between technical specifications and design documents?
What are technical specifications? Are they the same as design documents. If not, what is the difference and some examples?
3
votes
1answer
314 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 ...
0
votes
3answers
2k 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
441 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
179 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 ...
5
votes
6answers
1k views
What is the best way to prove that in-code documentation is greater than extensive external documentation?
What is the best way to prove to my boss that in code documentation is greater than extensive external documents containing documentation and screenshots of code/ui?
We have a group in the company ...
4
votes
1answer
91 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
267 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 ...
