8 replies to this topic

[zeroradius]

Hey guys,

So I am about to scrap the test framework that I have been working on to learn OOP and MVC. I plan on starting my personal framework that I actualy plan on using for a long time to come. I want to create documentation for it as I go. I have never made documentation before thou. So how do you guys create your documentation?

I googled it and got a wikipedia result

Quote

Technical documentation
This is what most programmers mean when using the term software documentation. When creating software, code alone is insufficient. There must be some text along with it to describe various aspects of its intended operation. It is important for the code documents to be thorough, but not so verbose that it becomes difficult to maintain them. Several How-to and overview documentation are found specific to the software application or software product being documented by API Writers. This documentation may be used by developers, testers and also the end customers or clients using this software application. Today, we see lot of high end applications in the field of power, energy, transportation, networks, aerospace, safety, security, industry automation and a variety of other domains. Technical documentation has become important within such organizations as the basic and advanced level of information may change over a period of time with architecture changes. Hence, technical documentation has gained lot of importance in recent times, especially in the software field.
Often, tools such as Doxygen, NDoc, javadoc, EiffelStudio, Sandcastle, ROBODoc, POD, TwinText, or Universal Report can be used to auto-generate the code documents—that is, they extract the comments and software contracts, where available, from the source code and create reference manuals in such forms as text or HTML files. Code documents are often organized into a reference guide style, allowing a programmer to quickly look up an arbitrary function or class.
Many programmers really like the idea of auto-generating documentation for various reasons. For example, because it is extracted from the source code itself (for example, through comments), the programmer can write it while referring to the code, and use the same tools used to create the source code to make the documentation. This makes it much easier to keep the documentation up-to-date.
Of course, a downside is that only programmers can edit this kind of documentation, and it depends on them to refresh the output (for example, by running a cron job to update the documents nightly). Some would characterize this as a pro rather than a con.
Donald Knuth has insisted on the fact that documentation can be a very difficult afterthought process and has advocated literate programming, writing at the same time and location as the source code and extracted by automatic means.
Elucidative Programming is the result of practical applications of Literate Programming in real programming contexts. The Elucidative paradigm proposes that source code and documentation be stored separately. This paradigm was inspired by the same experimental findings that produced Kelp. Often, software developers need to be able to create and access information that is not going to be part of the source file itself. Such annotations are usually part of several software development activities, such as code walks and porting, where third party source code is analysed in a functional way. Annotations can therefore help the developer during any stage of software development where a formal documentation system would hinder progress. Kelp stores annotations in separate files, linking the information to the source code dynamically.

Do you recomend any of the auto documenting programs listed in the article or do you have your own way of doing it?

Thanks,
~Zero

[WingedPanther]

When I'm doing formal documentation, I write Functional and Technical specs in advance, then write the code with occasional comments in code. User documentation comes after it's all worked out. For me, in code documentation just doesn't get that formal.

[Raynes]

It depends on the language. I'm of the opinion that good code is the best documentation.

In Lisps, we have things called docstrings. These are strings of documentation that you can attach to vars (which are attached to functions and such), and this documentation can be looked up later with something like a `doc` function in the REPL. I love this style of documentation, because it's so versatile. You don't have to leave your REPL just to look up documentation.

Besides that, it's metadata, so it can be used by documentation tools to generate API documentation and such for your applications automatically, without doing anything that you don't do normally in your code. When I have these types of tools available to me, my documentation consists of docstrings, very occasional comments to explain cryptic pieces of code, and unit tests.


In languages where these tools aren't available to me, I still use comments sparsely. I typically use languages that encourage small functions/pieces of code that are pieced together to create larger functions/pieces of code to achieve a result. A lot of the time, code like this can document itself. It takes a certain amount of skill to know when a comment is necessary and isn't necessary, but that really goes for all languages. Yes, you can over-comment your code, and it's really easy to do.

So, unit tests, docstrings, small pieces of code, and strategically placed comments! :D

[zeroradius]

Alright thanks guys. I still think I should learn to document my code in case an employer requires it. I like the looks of ROBODoc and I printed out the user manual so i can give it a shot

[Red_Shadow]

Sporatically. ;)

[manux]

When I know I will reuse my code or some other people might, I usually just put some explicit docstrings in my functions and classes, but that's in Python (and in lisp ;) ).
In Java, when I have to, I only really document the classes (Javadoc comment style), and sometimes their methods when the name isn't clear enough.
In C, I'm seldom using any formal doc, but I've used Doxygen once or twice in some "multi-dev" projects.

I guess that the main recurrent tip is to use explicit names for everything. It's because it's true :D
As WingedPanther said, external documentation and occasional comments in the code probably does it most of the time too.

[zeroradius]

Well my reason for wanting to create documentation is that I was told a lot of companies require it but I have never done it before.

[DarkLordofthePenguins]

Personally, I write a box comment at the top of the source code file, containing a brief description of what it does or what purpose it serves, then I write comments throughout the code where I see appropriate.

[artificial]

I use comments and UML-diagrams. :)

Greets,
artificial