Documentation (best practices discussion. No code)

[Guest]

TL;DR

Give your opinion on writing/maintaining documentation for your code.

 

Long:
I don't know if it's just me, but it can be very difficult to read the code of others when they use advanced commands & abstract naming schemes.

I personally enjoy documentation that can read like a tutorial & then a reference guide that has all the methods/data types explaining what it is & why it exists. This usually exists for a well maintained technology like SFML.
 

However when working with others on a project it seems to be difficult to get others to write documentation on complex systems. I know it takes time & you just spent all that time writing code. Some people barely understand their own code but hand it off to others to build off of.

 

Do you write documentation for your code? Do you maintain it?

If you have written documentation for your code, have people thanked you for it? (IE, thanks for saving me that time of reading through hundreds/thousands of lines of code because you write 4 short paragraphs or had definitions for what functions/variables did)

 

One relative of mine worked at a large company & wasn't exactly a programmer but wrote a guidebook for a program the company used to teach how to use the program & be a reference if you had common errors.

 

EDIT:
I have been notified of a phenomenon called "Self documenting code" where one writes such concise & neatly formatted code that it's very easy to understand what's going on. However is this a viable technique to substitute independent documentation for large projects?

[trag1c]

My opinion is that if a piece of code is expected to be reused and not a one off piece for a single project that will not be touched again then it should be essentially self documented. If its a one off then hack it together and get it out the door as fast as possible with no regard to how bad the code looks. At the end of the day i hate spending additional time going over what i have already done and documenting it. It just seems easier to kill 2 birds with one stone. However some documentation is required but you could reduce it from multiple paragraphs to a couple small comments by having your code legible and intuitive.

 

Practices within industry ultimately vary person to person and company to company. The best thing you could possible do is stay consistent to the codebase. The code may not be the easiest to digest at first but after a little while it becomes 2nd nature to read it. But this only works if everything is consistent.

[wasab]

I like to comment everywhere. Very essential because I often have no freaking clue what I just wrote a couple of days or hours even, ago. 

[FlappyBoobs]

I write self documenting code. Everything complicated is split into easy to understand and well named functions, and then peppered with comments for the complicated bits. 

 

However, you also need to be a certain level to be able to make it easy to understand without looking stuff up. I write code for programmers, not for people still learning. This is important to take into account when writing code, who will be reading it? If you target is juniors, then you need to explicitly comment, if it is for senior programmers then the basics (e.g. Any function standard to the language) shouldn't be commented, because we know what it does already i.e. Don't comment "gets data from stream and converts to object" I can alresdy see that however if you are pulling 3 GUIDs called "p1, p2 and p3" then please tell me what they reference. 

[Unimportant]

6 minutes ago, FlappyBoobs said:

however if you are pulling 3 GUIDs called "p1, p2 and p3" then please tell me what they reference. 

...by giving them better names, not by commenting.

[FlappyBoobs]

2 hours ago, Unimportant said:

...by giving them better names, not by commenting.

In some webservices all you get is a list of guids, the documentation tell you what they are. 

[DevBlox]

Self-documenting code and README's + separate high-level documentation, trying to write things that don't change much (minimises time to maintain).

[Mira Yurizaki]

22 hours ago, fpo said:

Do you write documentation for your code? Do you maintain it?

It's work policy to write up documents, so as part of our software process, we document our code outside of the code. However updating it is a nebulous thing. We have a requirements repository that gets updated, but we don't have an overall design document that gets updated (one exists, but it hasn't been touched in forever). If anything, for developers, the "updates" are tied to the last change record that implemented the part of the code you're interested in.

 

Quote

If you have written documentation for your code, have people thanked you for it? (IE, thanks for saving me that time of reading through hundreds/thousands of lines of code because you write 4 short paragraphs or had definitions for what functions/variables did)

Probably, but stuff I've done outside of coding, like documentation for getting development environments setup, was more of a benefit to other people. Since we don't accumulate all of the design documentation into one massive document (besides, it'd get pretty headachy trying to maintain that), it becomes a pain in the butt to track it down sometimes.

 

I think the issue with our code base is simply the sheer quantity of things there are. It's a complex system and we try to break things down to handle specific aspects of it.

 

Quote

EDIT:
I have been notified of a phenomenon called "Self documenting code" where one writes such concise & neatly formatted code that it's very easy to understand what's going on. However is this a viable technique to substitute independent documentation for large projects?

I'm of the belief that the documentation isn't supposed to tell you how some feature is implemented, merely what the code is doing on a higher-level description. For example, if I'm using a state machine to manage the execution cycle of some function, I'll simply say "there's a state machine with the following states, and when it's in x state it'll do foo and when it's y state it'll do bar." But I'm not going to go "we store the current state of the execution cycle in 'currentState'"

 

Basically the documentation exists to tell you what the code does. It shouldn't tell you how it does it, barring certain exceptions.

[colonel_mortis]

I generally aim to document each function/method with a comment explaining the purpose and contract of that function (as well as choosing hopefully informative names for them). Within each function, it should be mostly self-documenting, but if there is anything that is non-obvious or which was a significant design decision then I aim to comment that to explain it too.

 

For code that is very obscure, such as concurrent algorithms, I have ended up with significantly more comments than code, to informally justify the correctness of the code. This is definitely the exception rather than the rule.

 

If the code is intended to be consumed by other people (as in a library), separate written documentation makes sense, but IMO for application code it often makes more sense to have the documentation inline with the code, so you can refer to the implementation while looking at the docs and vice versa. A high level architectural overview is definitely a good idea in larger code bases though.

[vorticalbox]

On 6/2/2019 at 8:50 AM, wasab said:

I like to comment everywhere. Very essential because I often have no freaking clue what I just wrote a couple of days or hours even, ago. 

This ends up having messy code with comments everywher, you should only comment code of its needed.

 

Such as the use of this in JavaScript

 

const results = {

    something: 'hello world',

    ...someCheck && { foo:'bar' }

}

 

Which will only put foo into the object of someCheck is true, I would assume most people would have seen this before and would require a comment to explain.

 

[Franck]

16 hours ago, vorticalbox said:

This ends up having messy code with comments everywher, you should only comment code of its needed.

 

Such as the use of this in JavaScript

 

 

const results = {

    something: 'hello world',

    ...someCheck && { foo:'bar' }

}

 

 

Which will only put foo into the object of someCheck is true, I would assume most people would have seen this before and would require a comment to explain.

 

Personally i never seen that form in JS. If it would fall on this code during a bug fixing session i would rewrite it my own way to make sure i know what it's doing.

 

I agree if you are barely 5 to 10 devs working on the project it might works great.

 

But, when you can have literally over 50 people that can debug in that portion of the site every month you will have a mix of skill set everywhere and quite a lot won't don't know these forms and will try to play around with it and will cause problem. And this from real world experience. These kind of issues comes in everyday.

 

How many times per week i have a junior come at me and ask me to help him out with his own code he can't figure out anymore and it takes me 30 min to an hour understand what he was trying to do. I have to ask him what he tried and then ask him what each lines are supposed to do in his mind one by one to grasp where his problem is. I usually go over with them and all i do is comment each lines telling what it is "supposed" to do.

 

Comments everywhere transform your code in self rubber ducking. If the line or small piece of code doesn't do what the comment says then there is a problem. You fix everything until the next comment and that's it. as long as the comment is true the code works "as designed"

[Sauron]

On 6/2/2019 at 3:16 AM, fpo said:

I have been notified of a phenomenon called "Self documenting code" where one writes such concise & neatly formatted code that it's very easy to understand what's going on. However is this a viable technique to substitute independent documentation for large projects?

I believe you should strive for self documenting code, but still write documentation. I don't like writing an essay for every function but a concise description of what the function does is important.

[Sauron]

3 hours ago, Franck said:

Personally i never seen that form in JS. If it would fall on this code during a bug fixing session i would rewrite it my own way to make sure i know what it's doing.

 

I agree if you are barely 5 to 10 devs working on the project it might works great.

 

But, when you can have literally over 50 people that can debug in that portion of the site every month you will have a mix of skill set everywhere and quite a lot won't don't know these forms and will try to play around with it and will cause problem. And this from real world experience. These kind of issues comes in everyday.

Ok, but you can't rewrite documentation for language syntax... otherwise you get stuff like

# does otherthing if thing is true.
# thing must be of type boolean
if thing:
	otherthing

which is just useless clutter - if someone can't figure that out just by looking at the code they should spend 5 minutes learning the bare essentials of the language they're professionally writing software in. I get that people do dumb things but the solution isn't to overdocument everything into oblivion. If you can't bother googling a piece of syntax you've never seen before messing with it chances are you won't read the comment right above it either.

3 hours ago, Franck said:

How many times per week i have a junior come at me and ask me to help him out with his own code he can't figure out anymore and it takes me 30 min to an hour understand what he was trying to do. I have to ask him what he tried and then ask him what each lines are supposed to do in his mind one by one to grasp where his problem is. I usually go over with them and all i do is comment each lines telling what it is "supposed" to do.

That's not a problem if you avoid garbled and incomprehensible code - yeah, commenting everything can help in these circumstances but if you need to do that the code is probably trash anyway; the comments are just a crutch and the sooner the core problem is addressed (the code is bad) the better.

[Franck]

58 minutes ago, Sauron said:

Ok, but you can't rewrite documentation for language syntax... otherwise you get stuff like

# does otherthing if thing is true.
# thing must be of type boolean
if thing:
	otherthing

which is just useless clutter - if someone can't figure that out just by looking at the code they should spend 5 minutes learning the bare essentials of the language they're professionally writing software in. I get that people do dumb things but the solution isn't to overdocument everything into oblivion. If you can't bother googling a piece of syntax you've never seen before messing with it chances are you won't read the comment right above it either.

That's not a problem if you avoid garbled and incomprehensible code - yeah, commenting everything can help in these circumstances but if you need to do that the code is probably trash anyway; the comments are just a crutch and the sooner the core problem is addressed (the code is bad) the better.

It's just a matter of experience and opinions. I have yet to have worked on a single project were method/function were coded appropriately with single responsibility. In my 21 years experience in business applications i have only worked with 3 other people that were actually coding properly. Self describing code is just never a reality in my world. I keep training people to do better but most people hate to change and that's that.

 

My most memorable moment was probably a complex formula that a single method and was just a tiny bit over 51,000 line of codes. People coding me 500+ lines of code in a single method without a single comment this is easily 50% of the methods i get to fix everyday.

 

No comment and self explaining code is not a reality for me.

[Sauron]

2 minutes ago, Franck said:

It's just a matter of experience and opinions. I have yet to have worked on a single project were method/function were coded appropriately with single responsibility. In my 21 years experience in business applications i have only worked with 3 other people that were actually coding properly. Self describing code is just never a reality in my world. I keep training people to do better but most people hate to change and that's that.

I would argue that that's more of an intrinsic problem of OOP doing more to confuse people than to actually help, but that's sort of beside the point. Obviously if you can't get people to write good code having them comment things is better than nothing, but why would someone who hates change so much be willing to change the way they write documentation?

4 minutes ago, Franck said:

My most memorable moment was probably a complex formula that a single method and was just a tiny bit over 51,000 line of codes. People coding me 500+ lines of code in a single method without a single comment this is easily 50% of the methods i get to fix everyday.

lmao that must be hell

[Franck]

1 minute ago, Sauron said:

lmao that must be hell

it was VB 3.0 code so yeah. Still i had to maintain and fix stuff in it once or twice a year....... for ~7 years 

[Guest]

To continue the discussion... 

how important is it to have planned out the project before writing code if the project is intended to be large scale? 

 

What kind of direction & leadership do you expect? What should be laid out in clear English before code is written? 

 

If you were brought into a project that had no planning nor documentation, what are your chances of staying? 

 

What are your thoughts on others writing documentation on systems you need to extend? 

What kind of information should one give you before expecting you to work on their code using an API/technology you’re not familiar with? 

 

Mention spam

Spoiler

@trag1c

@wasab

@FlappyBoobs

@Unimportant

@DevBlox

@Mira Yurizaki

@colonel_mortis

@vorticalbox

@Franck

@Sauron

 

[Mira Yurizaki]

Just now, fpo said:

 how important is it to have planned out the project before writing code if the project is intended to be large scale? 

 

What kind of direction & leadership do you expect? What should be laid out in clear English before code is written? 

I expect to have most of the requirements squared away. There's no point in even trying to prototype something if I don't know what the customer wants.

 

Though I'm in a particularly different segment of software development. My company does contract work, so we take customers who are asking someone to build something, rather than us building something and hoping there's a customer for it (though we do that from time to time).

 

Just now, fpo said:

If you were brought into a project that had no planning nor documentation, what are your chances of staying?

Depends on what it's supposed to be in the first place.

[Guest]

3 minutes ago, Mira Yurizaki said:

I expect to have most of the requirements squared away.

How in depth should that be? Elevator pitch level or the project planned & now we just need the code to fill in the spaces. As like a scale of 1-10 where 1 is elevator pitch. 

 

3 minutes ago, Mira Yurizaki said:

Depends on what it's supposed to be in the first place.

I’m looking at game projects that aspire to become licensed/funded games but I’m mostly looking at your thoughts. 

 

My perception on documentation:

Spoiler

Pre-production is the most important part of development. 

It imo should outline 90% of what the intended systems & behaviours should be. In this all the hopes and dreams of the design leader will be explicitly stated & explained with at bare minimum a few storyboards for the most core of mechanics. 

 

Throughout this, (from a game development perspective) each department lead will set fourth a standard for how things should be named/organized. 

All the programmers will write code like “thisIsANewVariable” and “This_Is_A_Function” for an example  

 

[Mira Yurizaki]

5 minutes ago, fpo said:

How in depth should that be? Elevator pitch level or the project planned & now we just need the code to fill in the spaces. As like a scale of 1-10 where 1 is elevator pitch. 

 

I’m looking at game projects that aspire to become licensed/funded games but I’m mostly looking at your thoughts. 

Requirements are everything you need and want the software to do. And they are all objectively testable. So on that scale, it's basically a 9 or 10. Telling me you want a "innovative combat system" for your game is not a requirement. Telling me "The player can input the following actions during combat: ..."  or similar is a requirement.

[Sauron]

@fpo I haven't actually been in such a project before so I can't really express a preference. In theory there are about half a dozen distinct ways you could effectively organize a large scale project, what actually works best is a subject of constant debate and varies depending on what you're trying to do.

[Guest]

2 hours ago, Mira Yurizaki said:

Telling me you want a "innovative combat system" for your game is not a requirement. Telling me "The player can input the following actions during combat: ..."  or similar is a requirement.

What would you do professionally if you were handed a project that aligned more so with 

“I want an innovative combat system” and non-leads constantly putting feature creep into the scope? 

 

(More or less the description of my situation & reason for making this thread.)

[Guest]

1 hour ago, Sauron said:

@fpo I haven't actually been in such a project before so I can't really express a preference. In theory there are about half a dozen distinct ways you could effectively organize a large scale project, what actually works best is a subject of constant debate and varies depending on what you're trying to do.

Do you think the planning & debating should mostly (90%) occur before coding/prototyping for a clear direction or do you think that the planning/debating should occur during programming to constantly shift the project to stay on top of trends & whatnot?

[Mira Yurizaki]

37 minutes ago, fpo said:

What would you do professionally if you were handed a project that aligned more so with 

“I want an innovative combat system” and non-leads constantly putting feature creep into the scope? 

 

(More or less the description of my situation & reason for making this thread.)

Depends if I'm in a lead position or not. If I'm not the lead or at least put in charge of the feature, I'm only going to salvage what I can.

 

Most of the things I do inside and outside of work that go anywhere typically have some end goal that's more or less well defined. Anything else ends up being an experiment to see what I can do.

[vorticalbox]

8 hours ago, Mira Yurizaki said:

I expect to have most of the requirements squared away. There's no point in even trying to prototype something if I don't know what the customer wants

100% agree there is nothing worse for a project than scope creep.