Doxygen niggles

| 6 Comments
I've been using Doxygen recently. It can scan a body of code and produce reams of linked documentation and diagrams. I, personally, don't really use it for its documentation, just for its diagramming. I've always believed that if I can't draw a neat and tidy picture of the relationships between pieces of code then the design needs fixing.

I used to drop in and out of drawing my own cut down version of UML diagrams as I designed code. When things got complicated I'd draw a diagram and when the diagram was hard to draw due to the twisted nature of the code I'd adjust the diagram until it was "nice" and then apply the same transformations to the code. It usually seemed to result in a better design. Now I try and let my tests drive my design and this diagramming phase seems to have lessened in importance.

My hand drawn UML-like diagrams weren't usually kept; often other people on the team didn't know my version of UML (or even the real thing) well enough to get much out of the simple diagrams so there wasn't much point in keeping them. More importantly they broke the DRY principle - the diagrams were derived from the code but maintained separately. As soon as the ink dried they were likely to be out of date and out of sync with the code.

The fact that Doxygen automatically generates the diagrams from the code removes the DRY issue; add a Doxygen build step to your build and the diagrams are always up to date. That they can either be in 'UML' or a cut down format and that the format is down to how the tool generates them and not some personal choice removes a lot of the 'discussion' about how best to represent the code in pictures. That they're embedded in 'documentation' and clickable and the clicks let you navigate to the documentation or the source means that they're much more use than hand drawn diagrams.

Doxygen1.png

I'm not one for masses of comments in code, and I abhor those block comments that explain ever parameter in long winded text that tries so hard to add value over that given by appropriate naming, but... Once you're using Doxygen for diagrams you may find that adding a few comments that indicate intent rather than process can make the generated documentation more useful.

Doxygen2.png

My problem with Doxygen is that its parser isn't quite as clever as it could be. I use namespaces a lot. I find them useful. I always use the fully qualified namespace name in header files; I have a rule about not using using directives in headers. In cpp files though, I usually have a bunch of using directives at the top to make the code less cluttered. I'm not sure if it's good, but it works for me.

6 Comments

Dear Len,
Can you tell me something about P2P technology. Recently i downloaded an application of voice communication known as Skype (www.skype.com). The main feature is that it simply works if two terminals are present at different LANs; despite that there is no centralize server. On searching, i found out that the software uses P2P technology just like Kazaa (http://www.skype.com/skype_p2pexplained.html)

But i am unable to understand that how is this possible. After becoming a master of socket programming, my concept is that, two PCs over internet can communicate with each other directly if and only if atleast, any one is on live IP. If both are using private addresses they can't communicate and need centralize server.
But i am unable to understand how P2P technology works. Do you have any idea ??

Doesn't this part of the Skype document explain how they do it;

"Non-firewalled clients and clients on publicly routable IP addresses are able to help NAT’ed nodes to communicate by routing calls. This allows two clients who otherwise would not be able to communicate to speak with each other. Because the calls are encrypted end-to-end, proxies limit the security or privacy risk."

So they use non NAT clients as routers for the NATed clients.

It means that there is something in the "middle" (somethng like centralize server). Am i right ??

Yes there's something in the middle. No, it's not a centraized server, it's just another node.

There's a small problem with the doxygen link :-( it doesn't work! I presume you mean www.doxygen.org instead of the local non existent page (archives/www.doxygen.org)

Fixed, thanks.

Leave a comment