Click here to Skip to main content

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.

Re: CCC 2021-07-07 solution

jsc427-Jul-21 6:06

7-Jul-21 6:06

I haven't solved one in months. The CCC wasn't there when I looked this morning, so I looked after lunch and it was there, then. It took me about 4 mins, which I was very pleased about. But, before submitting I thought I'd better check whether the solution had arrived. It had, three minutes earlier, so it was too late to post. Never mind, maybe in a few more months, another one will come along that I can manage.

Re: CCC 2021-07-07 solution

Greg Utas7-Jul-21 6:14

7-Jul-21 6:14

If you managed this one, I don't think it'll take you months to manage the next one!

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

Doxygen is not documentation

den2k887-Jul-21 1:31

7-Jul-21 1:31

Elephant | [mastadon]

Elephant | [mastadon]

Elephant | [mastadon]

Elephant | [mastadon]

Elephant | [mastadon]

Elephant | [mastadon]

ing devs who rename their Doxygen Sunshine | [little ray of sunshine]

Sunshine | [little ray of sunshine]

as documentation and call it a day. Now I know precisely what public members your library defines (reading the code is out of fashion) and nothing at all on how the Elephant | [mastadon]

Elephant | [mastadon]

I am supposed to use it.

Mad | :mad:

Mad | :mad:

Mad | :mad:

Mad | :mad:

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

Re: Doxygen is not documentation

OriginalGriff7-Jul-21 1:33

7-Jul-21 1:33

Those aren't devs - those are script kiddies. Sigh | :sigh:

Sigh | :sigh:

"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!

Re: Doxygen is not documentation

CPallini7-Jul-21 1:38

7-Jul-21 1:38

Indeed.

"In testa che avete, Signor di Ceprano?"
-- Rigoletto

Re: Doxygen is not documentation

Greg Utas7-Jul-21 1:39

7-Jul-21 1:39

The code is the urtext, and its documentation is a derivative work to help readers understand it. Cluttering and defiling it with tags to the point where it has to be exported by a tool is an abomination. Dead | X|

Dead | X|

Mad | :mad:

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

Re: Doxygen is not documentation

Popular

honey the codewitch7-Jul-21 2:35

honey the codewitch

7-Jul-21 2:35

I have to agree with that. I really hate code where every function has a heckin' header on it. Just comment a description. If it takes more than one line to describe it, in most cases, write another function.

Real programmers use butterflies

Re: Doxygen is not documentation

den2k887-Jul-21 3:34

7-Jul-21 3:34

I don't mind headers, as long as they are sensible - I use spacing comments a lot and a small header works just fine. i.e. something like this is fine for me (about the max size I can tolerate for a header)

C++

/**
 * Function: connectionIsValid
 * Description: returns TRUE if the address of the client is acceptable
 * Arguments: 
 *              connectedClient: pointer to the sockaddr returned by accept()
 *              structLen:       lenght of sockaddr returned by accept()
 * Return:
 *              duo_bool_t TRUE if connection is accepted, FALSE if not.
 */

They are just an embellishment of a comment though, documentation is another thing entirely.

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

Re: Doxygen is not documentation

honey the codewitch7-Jul-21 3:35

honey the codewitch

7-Jul-21 3:35

Yeah, I don't care for that stuff, because to me it increases maintenance without (usually) adding much value beyond the description. I tend to lean on long, descriptive parameter names and hard typing everything I need to be as descriptive as possible, even if means using a bool instead of an int like a lot of people do. =)

Real programmers use butterflies

Re: Doxygen is not documentation

jschell7-Jul-21 7:38

7-Jul-21 7:38

If all you do is write simple methods then of course what you state is true.

But often methods fulfill complex needs that are not clear from the code itself. And comments are necessary to explain what need the code is fulfilling. A maintenance programmer should not be required to understand and be familiar with the entire application just so they can make a change in one method.

And that is an ideal world. Methods, especially in legacy code, often grow due to convenience and work load rather than because it was optimal. And with multiple requirements being met that way it becomes very difficult for maintenance programmers to make required changes without impacting the application in unexpected ways.

Re: Doxygen is not documentation

honey the codewitch7-Jul-21 7:46

honey the codewitch

7-Jul-21 7:46

Yeah, code rots. At some point it should be rewritten, and too often in the industry it gets punted until long after it's necessary to do it.

Fortunately I don't have to deal with that anymore. Laugh | :laugh:

Laugh | :laugh:

I document my design and architecture down to the code level usually, so the functions are pretty clear, if you read them.

But then I don't have to work on teams anymore, so I've shed a lot of the baggage/overhead that comes with that.

Real programmers use butterflies

Re: Doxygen is not documentation

Stefan_Lang10-Jul-21 22:38

10-Jul-21 22:38

Indeed. Good names and taking advantage of C++'s strong typing is good enough a documentation for 90% of all functions. I've often seen hard to read code that could be improved just by using appropriate names and the correct data types. int is overused - I've seen too many cases where bool or enums would be a much better fit, and increase readability too.

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)

This will get you...

etkid848-Jul-21 3:53

8-Jul-21 3:53

a big Bronx Cheer if you are using Doxygen, just saying. Poke tongue | ;-P

Poke tongue | ;-P

~d~

Re: Doxygen is not documentation

BernardIE53178-Jul-21 5:15

8-Jul-21 5:15

I do not believe that function needs any documentation as the function name and argument names are self explanatory as they should be. In my own work I rarely document for that reason. Also I am lazy

Re: Doxygen is not documentation

Popular

#realJSOP7-Jul-21 9:09

7-Jul-21 9:09

I've been called out in meetings and *thanked* for writing comments. We have a fairly high turnover rate where I work, and knowing that, I comment pretty much everything I do, not so much as the "what", but more the "why" of code. I also comment as if the person coming in behind me is fairly new at being a programmer.

I've actually gotten letters of commendation for my "drive towards more maintainable code".

Good comments are worth the effort and the clutter that necessarily comes with them.

We don't use Doxygen,

".45 ACP - because shooting twice is just silly" - JSOP, 2010
-----
You can never have too much ammo - unless you're swimming, or on fire. - JSOP, 2010
-----
When you pry the gun from my cold dead hands, be careful - the barrel will be very hot. - JSOP, 2013

re: "We don't use Doxygen

etkid848-Jul-21 3:55

8-Jul-21 3:55

Perhaps, now you have some influence, you can convince your employer and team to use Doxygen -- take your code to the next level. Cool | :cool:

Cool | :cool:

Java | [Coffee]

~d~

Re: re: "We don't use Doxygen

#realJSOP8-Jul-21 23:09

8-Jul-21 23:09

I'm a contractor. I have no influence.

".45 ACP - because shooting twice is just silly" - JSOP, 2010
-----
You can never have too much ammo - unless you're swimming, or on fire. - JSOP, 2010
-----
When you pry the gun from my cold dead hands, be careful - the barrel will be very hot. - JSOP, 2013

Re: Doxygen is not documentation

dandy728-Jul-21 4:22

8-Jul-21 4:22

This.

So much this.

Re: Doxygen is not documentation

Marc Clifton7-Jul-21 3:22

7-Jul-21 3:22

Amen. I nix'd using Doxygen for that very reason -- a screenful of tags for a 5 line function. It makes visually scanning the codebase a nightmare. Better to just document stuff in a separate file -- wiki, markdown, HTML, Word doc, whatever.

Latest Articles:
Client-Side Type-Based Publisher/Subscriber, Exploring Synchronous, "Event-ed", and Worker Thread Subscriptions

Re: Doxygen is not documentation

hpcoder211-Jul-21 0:00

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).

Re: Doxygen is not documentation

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

Re: Doxygen is not documentation

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;

Re: Doxygen is not documentation

RickZeeland7-Jul-21 1:44

7-Jul-21 1:44

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

Re: Doxygen is not documentation

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

Re: Doxygen is not documentation

jsc427-Jul-21 3:28

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.

General News Suggestion Question Bug Answer Joke Praise Rant Admin

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