Jump to content
  • Advertisement
Sign in to follow this  
Angelic Ice

Software-Documentation creates Clutter?

This topic is 680 days old which is more than the 365 day threshold we allow for new replies. Please post a new topic.

If you intended to correct an error in the post then please contact us.

Recommended Posts

Hello forum!

 

I have a quite weird issue. Whenever I start commenting my own code, it feels like the comments just add clutter and bloat the overall project.

The general usage of documenation seems somewhat clear to me. In order to generate a doc, I need to document my code.

But that bloats my code instead of making it more readable.

Whenever I submitted work to other projects, I simply did not care about the clutter at all. It was not my project, I would not be forced to work on it all the time anyway. If I need to look up a thing or two, I would open the doc instead of read the comments within the source files.

 

When I want to understand what my functions do, I simply read their names and I derive their purpose.

I feel like my naming of classes and variables is just very clear about what concepts I try to get through.

 

Additionally, while this might work on a small scale project, it will probably fail on large ones - with many other developers and some that might chime in at any given time. They would be clueless with a project of tons of classes.

 

But whenever I see my documented code, I start to shiver because of how my documentation just created a storm of symbols.

Very simple example:

	//! Getter for (insert semantical here).
	/*!
	\return integer that represents (...).
	*/
	int get_value() 
	{
		return (this->value);
	}

The way C++ handles comments in combination with one of all possible style conventions make this very ugly on my eyes.

Especially //! and //*! and \return just turn in into a massacre of symbols for me.

 

Is this it? Is that all I can do about it? Isn't there a way for (e.g. Visual Studio) providing me a more readable approach?

 

Before I started my project, everything was feeling slick and clean but yet lacking documentation (which of course plays an important role).

But now, all these functions need their overhead of a symbol-massacre.

 

This would look so much easier on my eyes and way better structured. I know, parsing this would become a bit difficult, but key-words like "returns" could with that issue:

        // Getter for (...)
        // Returns int value representing (...)
	int get_value() 
	{
		return (this->value);
	}

Sorry if this all looks like a rant, it is not meant to be one!

I'm just wondering if I'm the only one who ever encountered this and if there are any solutions to it?

 

I hope I did not cause any confusion, otherwise just let me know!

Thanks for taking your time!

Share this post


Link to post
Share on other sites
Advertisement

Like others, I use Doxygen for documenting code. In my view, the documentation acts as an interface description. What does the function do, what goes in, and what goes out.
For the latter, meaning of values and boundaries of input and output are particularly important.
The documentation and the function header should be sufficient to call the function, and understand what you will get back.

I add the documentation to the .cpp file, as much as possible. It keeps the include files compact and readable, and the documentation is close to the code, which makes keeping it consistent simpler.
As an added bonus, the documentation header above the function acts as a visual clue that a new function starts.

For big enough functions, writing documentation is always useful. For small functions it is more questionable. However, that raises the complicated question of "when is it small?". To avoid that question, I simply write documentation for everything. The getter-like functions are very trivial to document.

 

To make sure errors don't creep into the documentation, I regularly build the documentation (as part of the script that updates my repository from upstream). I don't actually use the generated documentation much. I find it more convenient to open the file, and read it there.

 

Last but not least, there is a lot you can do with colours in your editor.

[attachment=33842:comment.png]

and a header fragment

[attachment=33843:comment1.png]

The dark-grey against the almost black background make the comment unobtrusive

 

 

 

Share this post


Link to post
Share on other sites

Don't comment every piece of code. Code should be readable.

Usually you don't comment getter/setter methods. (Unless they have side effects which is bad).

Naming conventions are more important than comments, if you give a good name to your method, you probably would not need to comment it.

From here it goes further, you have to build your methods and functions right in order to give them meaningful functionality and names.

For example a function called "Update"- What does it update? How does it do it? That's not a good name.

UpdateGunAmmunitation- This is a better name, it states what it updates.

 

Good comments explain something beyond the code. Algorithms, bugs, todos...

The only places I advise you to add comments even if they are cullter are interfaces and public APIs. (which most of the time are also interfaces).

Share this post


Link to post
Share on other sites

I do most of my work in C#, so I do use the triple-slash xmldoc comments from time to time.  Mostly I do this for my own purposes, because that stuff gets picked up by Visual Studio Intellisense, and can be helpful.  Note that this is essentially function-level comments.  I also use some ReSharper plugins that can parse these xmldoc comments to determine if a function could throw a particular type of exception, so I try to add those to help me out as well.

 

I have used Doxygen on our codebases before, but aside from the graphing capabilities, to get a sense of the structure of a projects, I haven't found it terribly useful.  I was originally hoping people might actually read the docs, but was sadly mistaken in the reality.

Share this post


Link to post
Share on other sites

Mostly I do this for my own purposes, because that stuff gets picked up by Visual Studio Intellisense, and can be helpful. Note that this is essentially function-level comments.
I also found this to be the most useful form. You get a compact description with all the little details that you must know at the time you need to know.

 

I was originally hoping people might actually read the docs, but was sadly mistaken in the reality.
People don't read generally if they can avoid it. They rather spend hours using a search engine and get nowhere.

 

Especially for technical documentation, you must understand its structure, and you need experience to recognize irrelevant details for the problem you are solving today. Once you have those skills though, documentation does give you a boost in productivity, especially in bigger projects, or longer running projects.

Share this post


Link to post
Share on other sites

Personally, I prefer that there would be good documentation, and the code is cluttered, vs no documentation and the node looks neat.

Because in my experience, programmers will often time name their functions, variables, and arguments some of the stupidest crap I have ever seen. Because if you can't identify what the hell the function does by it's name, then you need to look at it's documentation. If it's documentation is none existing because the programmer thinks that it's "Straight forward" your only other option is to actually DIG into the function's source files if you can't get ahold of the original programmer.

 

And if you come across crap like Dt, which does not mean delta time like any sensible person would think it means, and instead figure out that Dt is actually a reference to the rendering engine.... well it's time to print the code off on paper and go strangle the programmer with it.

 

There are also moments where a function seems like it's self documenting, but does something hidden in the side lines that is not very intuitive by face value.

 

Typically I get by-by doing this.

/* For functions or Variables that are self explanatory but have nothing hidden I tend to do this. */

bool loadDataTable(const w_char* FilePath, DataBase** OUT_DataBase); ///Function to load data. Returns false under failure.
bool initLevel(const LevelForm** Level_Data)                         ///Loads level from memory. Returns False under failure.

void setActorValue(const w_char* Name, int value);

/* for functions that requires a bit of explanation... */


/// Name: Set Skeletal Parameters
/// Note: This function is designed to set a series of bones on an
///       armature to some unique data. Arguments are best not filled
///       manually, but instead by the assistance of helper functions and
///       data structures.
/// @input param Data: A pointer to either an array of structs, or a linked list.
/// @input param count: A const integer that details how many bones are inside the linked list.
/// @input Skel_Descrip: A pointer to a description detailing all important information about a skeleton as a whole.

And yes, we do need a description about a skeleton in our current engine. It's because the skeleton it's self does hold more data than normal. Such as how an animated body's Bounding box needs to be calculated. If it should be calculated per limb, or as a point cloud of points that are defined in each bone. If the Skeleton is static (animations do not move the player), or dynamic (animations moves the player). etc.

Edited by Tangletail

Share this post


Link to post
Share on other sites

It's not the documentation, but the practice of how you write your documentation that creates clutter.  Like almost everything else, there's a good and bad practice of writing documentation and comments.

 

Could you blame the code for being a spaghetti code?  No.  Spaghetti code is the result of writing poor code.

 

Your confusion and clutter is the result of writing poor documentation.

Share this post


Link to post
Share on other sites
Sign in to follow this  

  • Advertisement
×

Important Information

By using GameDev.net, you agree to our community Guidelines, Terms of Use, and Privacy Policy.

We are the game development community.

Whether you are an indie, hobbyist, AAA developer, or just trying to learn, GameDev.net is the place for you to learn, share, and connect with the games industry. Learn more About Us or sign up!

Sign me up!