Click here to Skip to main content
15,918,624 members

Welcome to the Lounge

   

For discussing anything related to a software developer's life but is not for programming questions. Got a programming question?

The Lounge is rated Safe For Work. If you're about to post something inappropriate for a shared office environment, then don't post it. No ads, no abuse, and no programming questions. Trolling, (political, climate, religious or whatever) will result in your account being removed.

 
GeneralRe: Silly Documentation Question Pin
glennPattonWork316-Apr-24 21:55
professionalglennPattonWork316-Apr-24 21:55 
GeneralRe: Silly Documentation Question Pin
Salvatore Terress17-Apr-24 2:16
Salvatore Terress17-Apr-24 2:16 
GeneralRe: Silly Documentation Question Pin
Mike Hankey16-Apr-24 7:29
mveMike Hankey16-Apr-24 7:29 
GeneralRe: Silly Documentation Question Pin
Gary Wheeler17-Apr-24 1:02
Gary Wheeler17-Apr-24 1:02 
GeneralRe: Silly Documentation Question Pin
Mike Hankey17-Apr-24 1:24
mveMike Hankey17-Apr-24 1:24 
GeneralRe: Silly Documentation Question Pin
Gary Wheeler17-Apr-24 1:33
Gary Wheeler17-Apr-24 1:33 
GeneralRe: Silly Documentation Question Pin
Mike Hankey17-Apr-24 1:37
mveMike Hankey17-Apr-24 1:37 
GeneralRe: Silly Documentation Question Pin
trønderen17-Apr-24 6:43
trønderen17-Apr-24 6:43 
My experience with Doxygen (my own direct use and how I have seen numerous co-workers use it) is that it is fine for the bottom level documentation. The reader will know all the details about the third argument to a given method, but without a clue about when, where and why that method is called at all. The protocol, both any line protocol and the protocol of interaction between methods in one module and the interaction between modules.

In principle, you can add information about module and object interaction, line protocol specifications etc. My experience is that developers never get around to it Round Tuit[^]. Documenting the third parameter in a Doxygen comment is easy to do when you are editing the code; the higher level documentation is postponed until the next tuit delivery. (But sending the order has been postponed ... Smile | :) ).

As long as the intermediate levels are documented well, from the top level, the main subsystems and their interactions, and then stepwise down to modules and objects, then the reader might as well dive right into the source code. When you understand the use of some component, you have no need for a Doxygen carbon copy of the details that you will find in the source code anyway. Too often, Doxygen 'documentation' is little more than a rephrasing of method header.

Obviously, this very much depends on how developers use Doxygen. I am referring to what I have observed, not what you in theory can do with Doxygen.

Equally important: This is certainly not Doxygen-specific. Give the same developers another documentation system that they can maintain as part of the code editing, and the result will be very much of the same. You see it everywhere, in almost all software and documentation available on internet: Method headers and parameters are documented; how these are intended to be used is often completely omitted. If there are some traces of it, it is often poorly written. (The best way learn the use of some library, server etc. is to search for some other open source code to see how they are using it!)

So, my advice is: Forget about the source code documentation, at the method header and parameter level (with the exception of APIs exported to users outside your organization). Document it top-down, with focus on component interactions. If there are explicit protocols across a line, describe it, but document the protocol, not the API! E.g. MSCs can be very helpful to understand the component interactions. You can even make MSCs for protocols between modules or objects, even if they are not line protocols.

Document data structures thoroughly, but again: Top down. What kind of information is held in each structure, which components have access to it, which component maintains it. I am so old that I still think of ER as a good data modelling tool; today it is about as non-PC as the riverfall model, but you can have an ER-like approach even if you do not use ER notation. Stick to abstract data types - at this level it doesn't matter if a counter is 16, 32 or 64 bits. It does matter that it is a counter, though!

If it suits the software, state diagrams and/or state tables are great documentation tools. Unfortunately, few young developers have a good grasp on state transitions; it is more like a vague, remote concept in the same class as the OSI 7-layer model Smile | :) .

So how far down should the documentation go? My answer is clear (but lots of people will frown): Write your documentation so that it is independent of programming language. If the system is re-implemented in, say, Fortran or Pascal, all of you documentation should still be valid. It should contain the language independent stuff, all the language independent stuff and nothing but the language independent stuff.

When you need code snippets or declarations to make your point, leave it to the source code itself. Your documentation tells what it should do. How does it can be seen from the code.

There is one big pitfall, though: When you start describing your system as a set of well documented(/defined) protocols, MSCs, a bird's eye on the data structures, state transitions etc., chances are that you will utter a few nasty words about how the system should have been written. You'll discover messy transitions, irregular use of interaction protocols, undisciplined access to data structures, ... There will be a lot of new entries in the ToDo-list! Just make sure to get that tuit order in the mail as soon as possible Smile | :)

Religious freedom is the freedom to say that two plus two make five.

GeneralRe: Silly Documentation Question Pin
Mike Hankey17-Apr-24 6:47
mveMike Hankey17-Apr-24 6:47 
GeneralRe: Silly Documentation Question Pin
trønderen17-Apr-24 8:51
trønderen17-Apr-24 8:51 
GeneralRe: Silly Documentation Question Pin
Mike Hankey17-Apr-24 9:18
mveMike Hankey17-Apr-24 9:18 
GeneralRe: Silly Documentation Question Pin
charlieg18-Apr-24 17:05
charlieg18-Apr-24 17:05 
GeneralRe: Silly Documentation Question Pin
charlieg18-Apr-24 17:26
charlieg18-Apr-24 17:26 
GeneralRe: Silly Documentation Question Pin
rob tillaart16-Apr-24 20:50
rob tillaart16-Apr-24 20:50 
GeneralRe: Silly Documentation Question Pin
glennPattonWork316-Apr-24 21:54
professionalglennPattonWork316-Apr-24 21:54 
GeneralRe: Silly Documentation Question Pin
Nelson Goncalves Oct202217-Apr-24 2:17
Nelson Goncalves Oct202217-Apr-24 2:17 
GeneralRe: Silly Documentation Question Pin
jochance18-Apr-24 5:58
jochance18-Apr-24 5:58 
GeneralRe: Silly Documentation Question Pin
charlieg18-Apr-24 17:17
charlieg18-Apr-24 17:17 
GeneralWhat sort of performance should I expect? Pin
dandy7216-Apr-24 5:03
dandy7216-Apr-24 5:03 
GeneralRe: What sort of performance should I expect? Pin
PIEBALDconsult16-Apr-24 5:35
mvePIEBALDconsult16-Apr-24 5:35 
GeneralRe: What sort of performance should I expect? Pin
dandy7216-Apr-24 5:46
dandy7216-Apr-24 5:46 
GeneralRe: What sort of performance should I expect? Pin
jochance17-Apr-24 8:01
jochance17-Apr-24 8:01 
GeneralRe: What sort of performance should I expect? Pin
k505416-Apr-24 6:04
mvek505416-Apr-24 6:04 
GeneralRe: What sort of performance should I expect? Pin
dandy7216-Apr-24 7:00
dandy7216-Apr-24 7:00 
GeneralRe: What sort of performance should I expect? Pin
k505416-Apr-24 7:10
mvek505416-Apr-24 7:10 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.