Tagged Questions
1
vote
1answer
86 views
Is there a tool to generate multi-goal procedural instructions? [closed]
As a user: When I have good instructions to follow I'm sure I could do just about anything. With poor instructions I end up frustrated, wasting time and probably giving up.
The type of instruction I ...
0
votes
2answers
261 views
How to write comments to explain the “why” behind the callback function when the function and parameter names are insufficient for that?
How should I approach writing comments for callback functions? I want to explain the "why" behind the function when the function and parameter names are insufficient to explain what's going on.
I ...
1
vote
0answers
88 views
Is there a unified source code documentation generator? [duplicate]
I'm currently working on a client's project that involves programming in multiple languages. It has gotten to the point where the amount of source code for each language has grown to such a large ...
6
votes
1answer
247 views
Is there a de facto standard documentor for Javascript?
I'm trying to document my code using JSDOC3, that has a similar syntax to PHPDocumentator / Apigen. But is there a de-facto standard for Javascript inline documentation? I think Google Closure is the ...
5
votes
1answer
568 views
Duplicating documentation on interface implementations/overrides good or bad?
So we have an interface like so
/// <summary>
/// Interface for classes capable of creating foos
/// </summary>
public interface ICreatesFoo
{
/// <summary>
/// Creates foos
...
4
votes
1answer
1k views
Does doxygen support templates for the HTML output?
I've documented my code for doxygen, but I don't want the default HTML it gives. I know I can customize it by providing custom CSS, headers, footers, etc. (like GNOME does), and how I can add common ...
2
votes
1answer
441 views
documentation of typescript code [closed]
my question is rather short:
How do I document typescript code properly?
I found out that for projects becoming bigger and bigger, it is important to look at a function and immediately know ...
5
votes
2answers
141 views
Seeking advice on system documentation
I have a rating engine (it is basically an algorithm) which when I started had no formal documentation. We have created a functional specification/decomposition which is our business level document ...
8
votes
3answers
162 views
How to document experimental or incomplete APIs like @deprecated?
Is there a good term that is similar but different than "deprecate" to mean that a method or API is in the code base but should not be used because its implementation is not complete or will likely ...
1
vote
1answer
322 views
How to document unlimited argument parameters?
In PHP you can have a function take an infinite number of arguments like
/**
* Do abc...
*
* @since 1.0
* @param mixed $arg1 Arg description
* @return string ...
2
votes
2answers
267 views
HTML in docblock comments?
In the PEAR standards there is no reference to HTML, if its allowed or not.
http://pear.php.net/manual/en/standards.sample.php
But I see some people use HTML tags like <kbd> and stuff..
So is ...
3
votes
5answers
556 views
How do you keep track of the meaning of your SQL fields?
The more SQL fields I add to my tables and the more primary/foreign keys I add the more I lose the overview for specific fields for certain scenarios like Get/Add/Delete/Update data.
I use SQL ...
10
votes
7answers
889 views
Where to put code documentation?
I am currently using two systems to write code documentation (am using C++):
Documentation about methods and class members are added next to the code, using the Doxygen format. On a server Doxygen ...
21
votes
4answers
949 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 ...
6
votes
5answers
426 views
Where should a programmer explain the extended logic behind the code?
I have developed a few quantitative libraries in C# where it is important to understand not only the classic information that goes with the XMLDoc comments (which contains basic information with the ...
20
votes
5answers
832 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 ...
4
votes
3answers
175 views
What could be some pitfalls in introducing a style guide and documentation generating software in a development team?
I'm considering using appledoc, a flavor of Doxygen for use in generating Objective-C code documentation, in order to create documentation for my company's iOS apps. The idea is that a server will ...
7
votes
5answers
478 views
Whats sort of platform should I host documentation on? [closed]
We have a web-based software product that has a growing user-base of around 200+ people.
I won't go into details on our current workflow, but it involves word documents and converting to HTML and I ...
12
votes
5answers
997 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 ...
3
votes
2answers
339 views
Using automated bdd-gui-tests to keep user-documentation-screenshots up do date?
Are there developpers out there, who (ab)use the CaptureScreenshot() function
of their automated gui-tests to also create uptodate-screenshots for the userdocumentation?
Background: Whithin the ...
2
votes
2answers
144 views
How do I follow DRY when documenting module structure and interfaces?
In this paper, it is recommended that one document the following:
module structure
module interfaces
If I'm writing detailed module structures and interfaces in a standalone document, aren't I ...
2
votes
2answers
719 views
Best way to manage minutes of meeting
What is the best way of managing minutes of meeting on daily bases ? Do we have to manage the documents in a repository like VSS or it can be maintained in a excel sheet itself.
Kindly share your ...
4
votes
1answer
396 views
How can the process of creating and maintaining documentation be improved?
I know it's a very subjective question , but this is one section of Software Engineering wherein I haven't seen any improvement in terms of how we can do it in a better way. I guess every programmer ...
0
votes
2answers
2k views
PDF or ebook Java API documentation [closed]
Since I have a long train ride to and from work I was wondering if there is a version of the Java API documentation floating around that I could put on my Kindle. It would be nice on the rare occasion ...
