Welcome to the Lounge

hpcoder211-Jul-21 0:00

hpcoder2

11-Jul-21 0:00

Doxygen is fine - its actually a great way of automatically annotating code to make a hyperlinked bundle that you can explore in a web browser. However, insisting on commenting every single class, method and parameter is certainly a waste of time IMHO when self-documenting code is in play (as it should be).

honey the codewitch11-Jul-21 2:34

honey the codewitch

11-Jul-21 2:34

YES TO THIS. All of my this.

Real programmers use butterflies

Gary R. Wheeler7-Jul-21 12:36

Gary R. Wheeler

7-Jul-21 12:36

Agreed. I have an intense dislike for over-commenting. I'll quote something Dan Saks, one-time Secretary of the ANSI/ISO C++ Standard Committee, said in a C++ class he taught at my employer:

"If at all possible, say it in code. Otherwise, say it in a comment."

I've followed this advice ever since. Careful naming eliminates most of the "what is this?" sort of comments that a lot of people write. If I'm implementing a specific algorithm or to a particular specification, I'll include that information in a comment. I despise text-mode graphic comments with cutesy graphics or anything of that crap. The only exceptions are I do occasionally use 'dividers' like this:

// ------------------------------------------------------------------------------
// Heading text
// ------------------------------------------------------------------------------

to partition logical sections of the code or declarations. We also have a change list tool as part of our automatic build process that constructs a change history correlated by version based upon comments in the source code.

Software Zen: delete this;

RickZeeland7-Jul-21 1:44

RickZeeland

7-Jul-21 1:44

SandCastle and MAML to the rescue!
MAML guide[^]
$Shucks | :-\$

honey the codewitch7-Jul-21 2:34

honey the codewitch

7-Jul-21 2:34

I know it's not ideal, but I enjoy technical writing, and I prefer to give my code the full treatment by way of articles. It is better than not doing, and it's more likely that I skip it if I hate doing it.

Real programmers use butterflies

jsc427-Jul-21 3:28

jsc42

7-Jul-21 3:28

I, too, like technical writing! It is like having a code review and training others. If you try to think like the reader and ask the questions that he/she/it would ask, it often highlights ambiguities and holes and missing features and redundancies.

Forogar 7-Jul-21 4:33

Forogar

7-Jul-21 4:33

It's much better to write the documentation with the aim of saying why you are doing something rather than just what. How many times have you seen something like the ultimate useless comment, "// Loop through the list"? Mad | :mad:

Doxygen is very clever in it's way but still basically useless.

- I would love to change the world, but they won’t give me the source code.

PIEBALDconsult7-Jul-21 3:09

PIEBALDconsult

7-Jul-21 3:09

Same thing with a tool one of my colleagues was trying to push on us to "document" our SQL Server databases a few years back. Whatever it can create automatically, is not documentation. And what could it possibly do which we can't do better ourselves?

honey the codewitch7-Jul-21 4:41

honey the codewitch

7-Jul-21 4:41

The main thing I use doxygen style stuff with doc comments for is in C# I can force my compiler to error out if I haven't commented a public method. I don't care about the XML doc file it generates. Laugh | :laugh:

Real programmers use butterflies

MadGerbil8-Jul-21 1:47

MadGerbil

8-Jul-21 1:47

Sometimes management forces you to write documentation - documentation that nobody ever will read - so you use a tool to pump out a steaming mound of pulp, show it to management, and move on.

The point is: Know your audience.

SeattleC++8-Jul-21 6:15

SeattleC++

8-Jul-21 6:15

Doxygen was documentation in the 1990s, before your IDE could show you all the classes in your project, and you had to have paper documentation. Not so much today.

Doxygen is not documentation if you don't use Doxygen comments to at least say what function args mean, but rely exclusively upon what Doxygen finds by itself, again because your IDE already does that.

Stefan_Lang10-Jul-21 23:10

Stefan_Lang

10-Jul-21 23:10

The problem isn't doxygen, the problem is people thinking that using such a tool creates useful documentation all by itself.

If you can't come up with sensible comments at the right places, sensible function and variable names, and clean code, then no tool in the world will magically turn that code into well documented code!

GOTOs are a bit like wire coat hangers: they tend to breed in the darkness, such that where there once were few, eventually there are many, and the program's architecture collapses beneath them. (Fran Poretto)

den2k8811-Jul-21 20:56

den2k88

11-Jul-21 20:56

Stefan_Lang wrote:
The problem isn't doxygen, the problem is people

I never blame the tool, only the people using it (except if the tool doesn't work properly, but Doxygen does).

GCS d--(d-) s-/++ a C++++ U+++ P- L+@ E-- W++ N+ o+ K- w+++ O? M-- V? PS+ PE- Y+ PGP t+ 5? X R+++ tv-- b+(+++) DI+++ D++ G e++ h--- r+++ y+++* Weapons extension: ma- k++ F+2 X

CCC 2021-07-07

Greg Utas6-Jul-21 23:11

6-Jul-21 23:11

star couple discard constellation (8)

Robust Services Core | Software Techniques for Lemmings | Articles
The fox knows many things, but the hedgehog knows one big thing.

pkfox6-Jul-21 23:39

pkfox

6-Jul-21 23:39

Is is asterisk ?

"I didn't mention the bats - he'd see them soon enough" - Hunter S Thompson - RIP

Greg Utas6-Jul-21 23:41

6-Jul-21 23:41

No.

Robust Services Core | Software Techniques for Lemmings | Articles
The fox knows many things, but the hedgehog knows one big thing.

OriginalGriff6-Jul-21 23:44

6-Jul-21 23:44

Perhaps Obelix? Getafix?
Nah ... it's Dogmatix!

"I have no idea what I did, but I'm taking full credit for it." - ThisOldTony
"Common sense is so rare these days, it should be classified as a super power" - Random T-shirt
AntiTwitter: @DalekDave is now a follower!

Greg Utas6-Jul-21 23:48

6-Jul-21 23:48

I think you know the answer is no. Big Grin | :-D

Robust Services Core | Software Techniques for Lemmings | Articles
The fox knows many things, but the hedgehog knows one big thing.

Oi Griff !

pkfox6-Jul-21 22:58

pkfox

6-Jul-21 22:58

Time for a Oi Greg Utas Big Grin | :-D

@petepjksolutionscom

"I didn't mention the bats - he'd see them soon enough" - Hunter S Thompson - RIP

OriginalGriff6-Jul-21 23:16

6-Jul-21 23:16

I was busy ... doing exciting things, like slicing ham and washing up. Sigh | :sigh:

pkfox6-Jul-21 23:35

pkfox

6-Jul-21 23:35

First one sounds OK Big Grin | :-D

"I didn't mention the bats - he'd see them soon enough" - Hunter S Thompson - RIP

OriginalGriff6-Jul-21 23:45

6-Jul-21 23:45

The first one causes the second though ... Sigh | :sigh:

Greg Utas6-Jul-21 23:42

6-Jul-21 23:42

I guess you're so remote that you have to butcher your own hogs, eh?

Robust Services Core | Software Techniques for Lemmings | Articles
The fox knows many things, but the hedgehog knows one big thing.

OriginalGriff6-Jul-21 23:48