Rant: document your code people !

[doc_bean]

:furious3: :furious3: :furious3:

I have to use some sort of 'middleware' software in order to implement some filters, the nice people who have written the code have decided in all their wisdom to not document in the cpp files at all and only give the shortest of API documentation, which isn't nearly enough to figure out how everything works, especially considering the amount of overloading being done :furious3:

So i've been wasting the last week and a half trying to figure out how to implement my code with theirs and i'm still no further.

The funniest part is, they've released the code as open source so everyone can use it. Good (!'§!çà luck people ! :furious3: :furious3: :furious3:

[Blodrast]

Ah, welcome to the wonders of other people's code!
It's always like that, doc_bean. It's always tricky to use other people's code, because it takes a long time till you can start doing anything with it - very steep learning curve. I'm sorry to say this, but you should try to get used to it. If you ever find nice code, well written, good documentation - consider yourself lucky, because those will be the exceptions.

[Whacker]

// includes for headers
#include "extreme anger.h"

// add angry faces here to set mood for post

:furious3: :furious3: :furious3:
// begin rant loop on morons who wrote code that I am trying to fix
// and didn't document it so it just makes my job that much harder

I have to use some sort of 'middleware' software in order to implement some filters, the nice people who have written the code have decided in all their wisdom to not document in the cpp files at all and only give the shortest of API documentation, which isn't nearly enough to figure out how everything works,
// add evidence that previous coders probably had no idea what the
// @#$#@$3 they were doing

especially considering the amount of overloading being done
// more angry faces to emphasize anger @ said stupidity

:furious3:
// relate sheer futility and time wasted on said effort, possibly add
// ideas on how to extract revenge on individuals using A. vat of crisco
// and B. jumbo sized thermos.

So i've been wasting the last week and a half trying to figure out how to implement my code with theirs and i'm still no further.
// finish up with closing statements

The funniest part is, they've released the code as open source so everyone can use it. Good (!'§!çà luck people !
// final angry faces to top it off

:furious3: :furious3: :furious3:
:balloon2:

[doc_bean]

:laugh4: :laugh4: :laugh4:

Priceless Whacker !

Blodrast: I've been in this situation before? I just needed to vent a little, if the api is illegible and contains smileys, it's time to take a little break...

[Blodrast]

//lots of nicely commented code


Now that's the way to properly document code! :laugh4: :2thumbsup:

doc_bean: I'm sure you have, and I'm sure you will be again, mate. Nothing wrong with venting. :yes:
Also, if you wanna look for the silver lining, I can clearly remember a situation where I was using some code that I wasn't sure what was supposed to do exactly... and it had some comments (not much, but I thought, hey, better than nothing)... it was all a bit complicated, not trivial, obvious code. So I went by the comments, but the stuff wasn't working as it was supposed to.
After looking, and looking, several days wasted, I figured out what the problem was. The problem was that the authors of the code did not have English as their primary language, so what they probably meant to write was the actual opposite of what they had written... In other words, the comments were blatantly wrong...

Morale of this story: sometimes, no comments is better! :sweatdrop:

[Alexander the Pretty Good]

lol, Whacker. That's great!

My sympathies, Doc. It's a practice I should get into more, although I'm not writing anything really complicated for my courses...

[The_Mark]

Ho, you should've seen the old EBBS. 100k lines with nary a comment.

[Gregoshi]

Documentation is boring. Besides, everyone knows their own code is so intuitive that any documentation or comments is redundant. The phrase back when I was a programmer was "The code is self-documenting." :laugh4:

Good luck doc.

Whacker, your post is a thing of beauty. :thumbsup: :laugh4:

[CountArach]

Well I remember last year when I was doing my final course in Software Development. We had a 3D Tic-Tac-Toe game going. I was trying to figure out the basis of the code. We were using the x, y, z axis. But for some reason the moron who did the code made it z, x, y or something. It was so infuriating to read it, because I had no idea what was going on. :furious3:

And lol Whacker, that was a great post.

[Whacker]

:bow:

I'm glad you enjoyed that my friends.

I'm inclined to agree with Gregoshi though. Have been re-teaching myself C/C++ over the past few weeks, and it's been some hard going. It's pretty much impossible for me to sometimes comment my code because I haven't a damn clue what exactly it's doing or how I made it work!! :shame: :embarassed: :sweatdrop:

:balloon2:

[_Martyr_]

C++ can be very tricky to read, no doubt about it! But in my experience Perl is about 10^100 times worse! Seriously, forget trying to figure other peoples' code out, when code you've written yourself a few months back WITH good commenting is nigh on impossible to maintain! :laugh4: