Sorry your browser is not supported!

You are using an outdated browser that does not support modern web technologies, in order to use this site please update to a new browser.

Browsers supported include Chrome, FireFox, Safari, Opera, Internet Explorer 10+ or Microsoft Edge.

Geek Culture / C++ style documentation symbols? ( @ /// /** )

Author
Message
Neuro Fuzzy
17
Years of Service
User Offline
Joined: 11th Jun 2007
Location:
Posted: 12th May 2011 10:52
Link
So, I think I've got my head straight on some code organization stuff. I've narrowed it down to three rules:

(1) If using a low to lowish level library, wrap EVERYTHING in own functions/classes.
(2) Avoid globals like the plague
(3) Add a comments, and at LEAST write a bit of documentation above the function, which is more descriptive than the name of the function. (IE "getVar()" doesn't have documented "gets the var")

I've coded a bit of stuff following these rules strictly, and it's looking pretty maintainable. (errm, not that like 300 lines of code requires tons of maintenence )
My question is... whenever I comment like "///" or "/**", I get a funny blue color. I've seen this stuff along with the @ symbol in comments, and I'm assuming it's documentation. However... I can't find any good descriptions of what it all actually does. I'm guessing that this isn't C++ really, just a standard that developed to get documentation from code?

this link described stuff alright, but it seemed to assume knowledge about the @ symbol, so I was a bit lost. Coooouuuld someone set my head straight on this?

Ps. My dad recently told me that he can always tell whether engineers wrote a piece of code, or a computer science engineer wrote a piece of code, because the engineer's code is the hard-to-maintain one filled with global variables and all other sorts of annoyances. I don't want to code like an engineer!


Tell me if there's a broken link to images in a thread I post, and I'll fix 'em.
Back to top
Profile PM Email
David R
21
Years of Service
User Offline
Joined: 9th Sep 2003
Location: 3.14
Posted: 12th May 2011 12:44 Edited at: 12th May 2011 12:49
Link
Quote: "My question is... whenever I comment like "///" or "/**", I get a funny blue color. I've seen this stuff along with the @ symbol in comments, and I'm assuming it's documentation."


What IDE are you using?

Just that, obviously // or /** will change the highlight colour because they're comments on an actual syntactic level. But using @ is a totally different ball game. It can either be an informal thing (where you manually add it and there's no automatic display or extraction of it) a tool related thing (Doxygen et al use @ for attributes which will be pulled out automatically when docs are generated) or if you're in MSVC it could also be a C# thing (I believe @ is built right into the code documentation of C# as it is in Java)

The link you provided is for autodoc, which extracts the @ fields to generate HTML documentation etc. If you're only documenting on a code level, it is arguably unnecessary. If you want tool-assisted doc generation though, pick a tool and use the syntax it provides

09-f9-11-02-9d-74-e3-5b-d8-41-56-c5-63-56-88-c0
Back to top
Profile PM Email Website
Fatal Berserker
14
Years of Service
User Offline
Joined: 2nd Jul 2010
Location:
Posted: 12th May 2011 12:53
Link
#region name
#end region

Back to top
Profile PM
David R
21
Years of Service
User Offline
Joined: 9th Sep 2003
Location: 3.14
Posted: 12th May 2011 13:07 Edited at: 12th May 2011 13:12
Link
Quote: "
#region name
#end region"


That's nice if you're using MSVC and want to collapse code sections... But I don't see how it relates to the question

Also I think functions in C++ are collapsible regions by default, using those editor hints is totally unnecessary (and although if you use #pragma region you can specify a comment, it's a pretty bad way to do it. It also doesn't accept all character types, since it's treated as a normal pragma rather than a comment - so you can sometimes get "Bad suffix on string" etc. if the comment is too long or uses certain symbols)

09-f9-11-02-9d-74-e3-5b-d8-41-56-c5-63-56-88-c0
Back to top
Profile PM Email Website
Van B
Moderator
22
Years of Service
User Offline
Joined: 8th Oct 2002
Location: Sunnyvale
Posted: 12th May 2011 13:15
Link
The engineer probably wrote the code in an afternoon, while the computer science engineer is still looking at ways to obfuscate it .

Really, code in your own style, don't try and emulate anyone. If you think you need a global, use a global! - you should learn why some habits are bad, don't assume anything. Often I let game logic dictate the coding style - what are the core requirements and what techniques suit that best. At the end of the day, who cares if someone else can't maintain your code - your coding, not trying to teach someone to code. The easier it is to adapt the code; the easier it is to replace the coder. The way I see it, if something needs changed in my code, then I'll be the one to change it - otherwise start from scratch - that's giving people 2 options, spoiling them almost.

Health, Ammo, and bacon and eggs!
Back to top
Profile PM Email
ionstream
20
Years of Service
User Offline
Joined: 4th Jul 2004
Location: Overweb
Posted: 13th May 2011 00:47
Link
Listen to Van B: I've read a lot of programming design things that say "doing this is EVIL" and the like. Practice your own style, program a ton and refine it. The more you refine it, the better it will be to yourself and other programmers. Comments are always great when other people need to understand whats happening.

Back to top
Profile PM Website
David R
21
Years of Service
User Offline
Joined: 9th Sep 2003
Location: 3.14
Posted: 13th May 2011 00:58
Link
Quote: "The easier it is to adapt the code; the easier it is to replace the coder. The way I see it, if something needs changed in my code, then I'll be the one to change it - otherwise start from scratch - that's giving people 2 options, spoiling them almost."


That's great for you, but crap if you work for an organization. What if you get hit by a bus tomorrow? (as per the proverbial bus number)

Your code is impenetrable because you were the only one who wanted to be called upon to edit it. And rewriting literally is not an option in almost all cases (unless a project has only just started)

09-f9-11-02-9d-74-e3-5b-d8-41-56-c5-63-56-88-c0
Back to top
Profile PM Email Website
Neuro Fuzzy
17
Years of Service
User Offline
Joined: 11th Jun 2007
Location:
Posted: 13th May 2011 02:18
Link
I'm using code::blocks, and from what it sounds like there isn't any built-in documentation generator. I'm guessing this syntax highlighting would be autodoc-style?



Actually... I just re-read that autodoc page I linked to. I have no idea why it wasn't making sense to me yesterday. Maybe I shouldn't post when I'm tired.

I definitely want to keep up the habit of documenting code.


Tell me if there's a broken link to images in a thread I post, and I'll fix 'em.
Back to top
Profile PM Email
Jeku
Moderator
21
Years of Service
User Offline
Joined: 4th Jul 2003
Location: Vancouver, British Columbia, Canada
Posted: 13th May 2011 21:30
Link
Quote: "That's great for you, but crap if you work for an organization. What if you get hit by a bus tomorrow?"


Exactly. I've worked for several large companies and they all say readability is key. When you're working with a language like PHP, you should almost always focus on readability over efficiency because you can always just add more RAM to a server. That might sound harsh but we're getting to a point in time where hardware is cheap enough to not make code cryptic. If I'm totally out of line, move along...


Senior Web Developer - Nokia
Back to top
Profile PM Website
Van B
Moderator
22
Years of Service
User Offline
Joined: 8th Oct 2002
Location: Sunnyvale
Posted: 14th May 2011 00:41
Link
Of course, when your job involves sharing code, then you have to play by the rules - but understand that I'm an IT department - I don't share the responsibility with anyone. My work 'ethic' has paid off, I haven't been out of work for 17 years.

Health, Ammo, and bacon and eggs!
Back to top
Profile PM Email
Neuro Fuzzy
17
Years of Service
User Offline
Joined: 11th Jun 2007
Location:
Posted: 14th May 2011 07:34
Link
:\ after programming a bit more... I've realized what you were talking about, Van B. It's not that efficient to comment a ton, and it's annoying to compartmentalize stuff with namespaces and no globals. At least I'm a bit more familiar with good team-coding habits. Once I start working with multiple people on the same project, I'll probably be more strict with commenting. For now... meh.


I do like wrapping library commands in my own functions. For example, I'm using SDL, so once you allocate a SDL_Surface, you have to deallocate it. Since I've wrapped it in my own class, I don't have to worry about forgetting to deallocate it, because all the deallocation stuff is handled in the class's destructor. I figure that I shouldn't be forced to worry about library-specific/lower level stuff when writing the main program logic.

Soo, for a single project, good code>clear code.


Tell me if there's a broken link to images in a thread I post, and I'll fix 'em.
Back to top
Profile PM Email
Diggsey
19
Years of Service
User Offline
Joined: 24th Apr 2006
Location: On this web page.
Posted: 15th May 2011 02:53
Link
It's not important to comment a ton, you just need to comment where parts of the code need to be clarified. There is nothing worse than pointless commenting (unless it's a tutorial for example)

eg:


No programmer needs or wants to see that. You should give meaning not description of what's already there:


[b]
Back to top
Profile PM Email Website
Back to top

Login to post a reply

Server time is: 2025-05-21 15:46:28
Your offset time is: 2025-05-21 15:46:28