Comments

[PlainName]

It literally takes zero effort to type extra characters that conveys a meaningful function name, or a variable name.

It literally takes zero effort to type in a program. You are talking the mechanics, which is typically thought-free. What does take effort is the creative thinking: the design of what the things does, how the various parts interact, how it is partitioned, etc. And part of that is thinking up names that describe fully, yet succinctly, everything the variable or function is about. Not just right now as it comes into your head but indefinitely (because no-one is going to change it once it's made it past the first compile).

I've thought up some brilliant names during my time (albeit not to do with programming) and some of them took months. Yet you reckon that you and anybody worthy of the title 'programmer' can come up with endless perfect names on the spur of the moment.

No, that's armchair warrior thinking. And I bet none of you variable names would tell me why it is there and how it should be used.

[coppice]

Yes, so best give up and do something else. Or, you could just add a comment to help out the viewer a bit. No-one is perfect, yet all we see here is the assumption that we must be. Or else... well, what?

Nobody says anything about giving up. It's about learning best practices. It literally takes zero effort to type extra characters that conveys a meaningful function name, or a variable name. I've seen way too many "helpful" comments that lead me to down to a garden path of misdirections, only because the code was re-factored a few years ago, leaving the comments unchanged and completely irrelevant.

Ah, the "some comments are wrong therefore all comments are wrong" zealotry.

Names don't indicate why and why not. Names dont indicate why you don't have to look at and comprehend a big blob of code in the first place.

He didn't really say that. He said one of the points I have also made, based on studying lots of code over decades. After a few years of continuing development the comments rarely say anything meaningful about the details of the code as it is today. Its doesn't even take a major refactor. General development is enough. It seems to heavily relate to another point I have made, that comments are not compiled and so never checked. When people modify code they tend to avoid touching any comments, like they carry a plague. So, comments never event attempt to follow the develop of the code after its initial release. The only best practice I have found is never ever trust anything in a comment, but use them as a last resort when you are really puzzled by the code. They might tell you something about the code you have, but more likely will tell you something fairly distorted about what the code looked like in its early days. Knowing what the original author intended has given me an inportant clue more than once.

[madires]

If you don't like my comments simply don't read them!

[PlainName]

After a few years of continuing development the comments rarely say anything meaningful about the details of the code as it is today.

They are history and can say things that the words comprising them don't: just being wrong says a lot about the code. Of course, if one sets out thinking they are pointless then the subtle usefulness will never be noticed. Happens in all fields, that.

[tggzzz]

After a few years of continuing development the comments rarely say anything meaningful about the details of the code as it is today.

They are history and can say things that the words comprising them don't: just being wrong says a lot about the code. Of course, if one sets out thinking they are pointless then the subtle usefulness will never be noticed. Happens in all fields, that.

Or even the unsubtle necessities.

I've seen zealots ignore comments, and thereby destroy necessary properties and preconditions.

[coppice]

After a few years of continuing development the comments rarely say anything meaningful about the details of the code as it is today.

They are history and can say things that the words comprising them don't: just being wrong says a lot about the code. Of course, if one sets out thinking they are pointless then the subtle usefulness will never be noticed. Happens in all fields, that.

Its not uncommon to find routines where someone clearly took a working routine that had the right framework to it, and produced an entirely different routine by reworking the heart of it. When there are a group of routines which all need to have the same call and return structure, so they can be called indirectly, its very common to see this development behaviour, and it makes sense. It not only reduces typing, but it helps to keep the group of routines consistent. However, its also common to find the first routine was thoroughly commented, then all the others were produced by replacing the core of the code, with no changes to the comments. So, unless you spot the commonality between the group, the comments can seem truly bizarre.

[Nominal Animal]

On that subject: it would be really nice if font creators also care whether the fonts render well without needing anti-aliasing / font smoothing. Some websites are completely unreadable because the fonts don't render correctly without anti-aliasing.

Absolutely true.

The Web Open Font Format (version 1, .woff, supported by now by even pretty old browser versions, and version 2 .woff2 by all current versions) contain the TrueType/OpenType font as-is in compressed format, plus some XML information about it.  That means if the font is hinted, hinting is available to the browser rendeder.  (Most browsers do apply cross-origin CSS policy, meaning the web fonts have to reside in the same domain as the HTML pages used; that's why just referring to some central web repository won't work well.  Also, the set of glyphs included in the web font can be trimmed down, so you generally want to make sure you have the full font, and not someones idea of what is the useful set of glyphs from the full font typeface.)

Most fonts have been designed for printing (high-resolution devices), and only some –– Noto, DejaVu, FreeFont in particular! –– for displays ("low-resolution" devices, in this context) and with wide Unicode coverage.

(Some older fonts, like Monaco (on Mac) and Verdana (on Windows) were designed for displays, and often have very good hinting so they render well even without bitmap versions and antialiasing, but they were designed at a time when only a much smaller subset of glyphs were used: for older character encodings like MacRoman, Windows-1252 and code page 437.)

I did start a new thread in News/Suggestions/Help forum, with an example of how Dave could ensure that code snippets and teletyped text would show up the same way in all browsers regardless of what fonts the user has installed.
I do believe DejaVu Sans Mono is quite legible down to small sizes, although for the very smallest sizes (8×14 pixels for example) bitmap monospace fonts can be even better.

The same applies to all web sites, and TrueType and OpenType fonts that are licensed, or one has a license to, use on ones own web site.  So it is definitely not difficult, just a few minutes work.  The actual work is in choosing the font in the first place, such that it indeed is rendered well on all sorts of devices, and not just on the graphic artist's perfectly color-calibrated 3840×2160 retina display in a perfectly-lit office!


All that does relate to code comments, in the sense that whoever is reading the code comments, is often approaching the source codebase from a different direction than the designer/author/developer team.  Compare the situation to a graphic designer: they very often focus on what is stylish and visually pleasing, as opposed to what is functional on many different types of devices (including window sizes and resolutions). For web pages, responsive web design is the counterbalance for that.

For code, I do believe good code comments are similar counterbalance against "if it seems to work, don't care and don't touch it", related to maintainability; specifically against the "seems to work" part.  If we know the developer intent/purpose for some chunk of code, for example noted in a short useful comment, we can compare that to the actual code, and qualitatively evaluate the "seems to work" part.

For example, when fixing simple bugs, such qualitative evaluation helps pinpoint suspicious code:  I personally focus first on code that differs most from its apparent/ostensible purpose (including comments).

That also means that I believe that when one does such code review, one should be ready and willing to update, add, and remove comments, even though it provides no functional changes at all.  Just like "responsive web design" is separate from plain old "graphic design", we developers should consider code review, analysis, and comment updating a separate valued/useful task we should regularly do.

[AntiProtonBoy]

It literally takes zero effort to type in a program. You are talking the mechanics, which is typically thought-free.

This part of your argument doesn't make sense. Why would you spontaneously write code if you don't have a full picture of the problem domain you are trying to solve? 

My point is that once you understand the problem and what code needs to be written, then you'd certainly know what functions are required implementation and how you should name them. Same goes with transient stuff like variables.

So instead of writing code like this:

Code: (c++) [Select]

/*
   Make a transform matrix that maps colours from the source gamut to the
   target gamut, both specified in CIE xy coordinates.

   SR - Source red primary in CIExy coordinates
   SG - Source green primary in CIExy coordinates
   SB - Source blue primary in CIExy coordinates
   SW - Source white point in CIExy coordinates

   TR - Target red primary in CIExy coordinates
   TG - Target green primary in CIExy coordinates
   TB - Target blue primary in CIExy coordinates
   TW - Target white point in CIExy coordinates

   Returns 3 x 3 colour transformation matrix
*/
auto trColourGamut(
   const std::array< double, 2>& SR, const std::array< double, 2>& SG, const std::array< double, 2>& SB, const std::array< double, 2>& SW,
   const std::array< double, 2>& TR, const std::array< double, 2>& TG, const std::array< double, 2>& TB, const std::array< double, 2>& TW ) -> std::array< double, 9 >
   {
   // Returns matrix that transforms source RGB to CIEXYZ
   auto S = trCIEXYZ( SR, SG, SB, SW );

   // Returns matrix that transforms target RGB to CIEXYZ
   auto T = trCIEXYZ( TR, TG, TB, TW );
   
   // Make the bradford matrix
   auto B = chrmAdapt( SW, TW );

   // We concatenate the source transform matrix, bradford matrix, and the inverse of target matrix
   return S * B * inv( T );
   }

You could just adopt a self-documenting style like this:

Code: (c++) [Select]

/*
   Make a transform matrix that maps colours from the source gamut to the
   target gamut, both specified in CIE xy coordinates.
*/
auto colourGamutMappingTransform(
   const CIExy& sourceRedPrimary, const CIExy& sourceGreenPrimary, const CIExy& sourceBluePrimary, const CIExy& sourceWhitePoint,
   const CIExy& targetRedPrimary, const CIExy& targetGreenPrimary, const CIExy& targetBluePrimary, const CIExy& targetWhitePoint ) -> double3x3
   {
   auto sourceMatrix = transformCIEXYZ( sourceRedPrimary, sourceGreenPrimary, sourceBluePrimary, sourceWhitePoint );
   
   auto targetMatrix = transformCIEXYZ( targetRedPrimary, targetGreenPrimary, targetBluePrimary, targetWhitePoint );

   auto bradfordMatrix = chromaticAdaptation( sourceWhitePoint, targetWhitePoint );

   return sourceMatrix * bradfordMatrix * inverse( targetMatrix );
   }

In the second example, you can clearly deduce what the code does and what the variables mean just by looking at it. The comment block is also reduced down to just a single brief paragraph, and doesn't need an elaborate description what the function inputs mean. Also note that I don't even need to describe what the input and return data types are, because I'm using a type system that is self documenting.

The above is a toy example, but you get the gist of it. Of course, naming length can be tweaked if you find them too verbose. But the point is, they are descriptive and alleviates the extra burden of writing comments that essentially duplicates code in English vernacular.

The only place where I'd expect variables to be thoroughly documented is at public facing API boundaries that abstracts entire submodules. These are expected to appear as part of a reference manual, which may be generated via doxygen, or some equivalent scraping tool. As for private implementation details, one shouldn't need to comment code with the same granularity. Opt for self documenting programming practices instead.

Essentially, what i wrote above is the point I'm trying to make all this time. But some people here apparently view discussions about best industry practices (literally enforced by big dev houses everywhere) as being like a zealot.

And I bet none of you variable names would tell me why it is there and how it should be used.

Actually they would, because there is an economic incentive for me to use descriptive variable names. I've written massive linear algebra libraries. I've built a whole bunch of GPU render pipeline logic for computer graphics. Image processing tools. You name it. Some of these projects have gotten so large, that the only way forward is investing a little bit more effort in good naming strategies and breaking up problems into self-documenting abstractions. Otherwise, maintaining such projects would be humanly impossible, or very expensive in terms of time and money. The less time I need to spend figuring out what the code does, the sooner i can ship a product. Deciphering cryptic abbreviations and being at the mercy of good comments that describe said cryptic code is a waste of everyone's time. Because any competent developer will tell you such comments are a unicorns that do not exist in practice.

They are history and can say things that the words comprising them don't: just being wrong says a lot about the code. Of course, if one sets out thinking they are pointless then the subtle usefulness will never be noticed. Happens in all fields, that.

If you want history, you use version control systems. These are excellent at showing diffs, along with commit details, etc. An out of date comment has no business being in the file, if it no longer has any relevance to the code in its present state.

[PlainName]

Why would you spontaneously write code if you don't know the problem domain you are trying to solve?

Time constraints, perhaps. Having an outline of what you will do and filling in the details as you get to them. Any number of reasons, no doubt all of which means you're a shit programmer but nevertheless reflect real life.

So instead of writing code like this:

Frankly, the first one was good: easy to take in at a glance. Names dead easy to see and find, easy to see what is being referred to, etc. The second... well, you have to actually read it, and you can't quickly spot what you're looking for. Without the line spacing it would be wall of text stuff.

[coppice]

Why would you spontaneously write code if you don't know the problem domain you are trying to solve?

Time constraints, perhaps. Having an outline of what you will do and filling in the details as you get to them. Any number of reasons, no doubt all of which means you're a shit programmer but nevertheless reflect real life.

Its very common for people to rush into writing code with only a vague idea of what they need it to do. This might be due to external pressures, or stupidity, which are bad reasons. There are, however, good reasons. Trying to see what some of the key low level operations might look like early on can help sort out where performance bottlenecks might cause problems down the line, and meaningfully guide the detailed design.

[PlainName]

Its very common for people to rush into writing code with only a vague idea of what they need it to do.

That is the reality, and saying they 'just' need to do it properly, however you define that, isn't going to change things much. Persuading them to add some info in comments is surely better than nothing.

[coppice]

Its very common for people to rush into writing code with only a vague idea of what they need it to do.

That is the reality, and saying they 'just' need to do it properly, however you define that, isn't going to change things much. Persuading them to add some info in comments is surely better than nothing.

We have a good 60 years evidence that it isn't better than nothing. You can change the software tools. You can't change people. I wonder if AI tools may start to match comments with code in a semi-rigorous way, That could revolutionise the value of comments, forcing them to be kept current and accurate, or the code won't build.

[PlainName]

Its very common for people to rush into writing code with only a vague idea of what they need it to do.

That is the reality, and saying they 'just' need to do it properly, however you define that, isn't going to change things much. Persuading them to add some info in comments is surely better than nothing.

We have a good 60 years evidence that it isn't better than nothing.

You might have. I'm intrigued how you get that evidence, though - was it just by asking people, seeing how flummoxed it made them when reviewing code, what?

In contrast, I have 40 years of actual experience that is is better than nothing. So there 

[coppice]

In contrast, I have 40 years of actual experience that is is better than nothing. So there 

You're just a kid. When you have more experience maybe you'll see things differently.

[vk4ffab]

Why does no-one write comments any more? Not even just something to say what the function is meant to do, never mind the intricacies of how it goes about that. Some cryptic 12-character name may mean something to the programmer but it's bugger-all use when coming afresh to get a birds-eye view of things.

And variables! Really, do babies die or something if you let on WTF a variable is about?

Here's the thing. The code I write is for me. If I feel nice and share my code, I expect the end user to be smart enough to read the code and understand how it works, if they are not smart enough to do that then its tough tits. If I was contributing code to someone else's project, I would comment as per the project standard.

Mostly though I have stopped sharing code I write because of the number of people that write to tell me I am a dumb dumb head because they were to stupid to read the code to work out what library they were missing and I am just to old and cranky to hold people's hands to do things beyond their skills and abilities.

[PlainName]

Way to go, Team Player 

[JPortici]

Why does no-one write comments any more? Not even just something to say what the function is meant to do, never mind the intricacies of how it goes about that. Some cryptic 12-character name may mean something to the programmer but it's bugger-all use when coming afresh to get a birds-eye view of things.

And variables! Really, do babies die or something if you let on WTF a variable is about?

Here's the thing. The code I write is for me. If I feel nice and share my code, I expect the end user to be smart enough to read the code and understand how it works, if they are not smart enough to do that then its tough tits. If I was contributing code to someone else's project, I would comment as per the project standard.

Mostly though I have stopped sharing code I write because of the number of people that write to tell me I am a dumb dumb head because they were to stupid to read the code to work out what library they were missing and I am just to old and cranky to hold people's hands to do things beyond their skills and abilities.

fair
however the older i get the lazier i am and i'm too lazy already to work out what two-year-ago me did and why he did it. curse that lazy bastard for not commenting. so over time i reached a sweet spot for comments, variable and function names, also stripping away all possible "clever" things i did in the past unless they were really, really, really justified. The truth is that i'm always part of a team even when i'm the sole developer, and the other team member is my past self (or my future self, depending on how you look at it) which counts toward "another person that has to read and understand the code"

[vk4ffab]

Why does no-one write comments any more? Not even just something to say what the function is meant to do, never mind the intricacies of how it goes about that. Some cryptic 12-character name may mean something to the programmer but it's bugger-all use when coming afresh to get a birds-eye view of things.

And variables! Really, do babies die or something if you let on WTF a variable is about?

Here's the thing. The code I write is for me. If I feel nice and share my code, I expect the end user to be smart enough to read the code and understand how it works, if they are not smart enough to do that then its tough tits. If I was contributing code to someone else's project, I would comment as per the project standard.

Mostly though I have stopped sharing code I write because of the number of people that write to tell me I am a dumb dumb head because they were to stupid to read the code to work out what library they were missing and I am just to old and cranky to hold people's hands to do things beyond their skills and abilities.

fair
however the older i get the lazier i am and i'm too lazy already to work out what two-year-ago me did and why he did it. curse that lazy bastard for not commenting. so over time i reached a sweet spot for comments, variable and function names, also stripping away all possible "clever" things i did in the past unless they were really, really, really justified. The truth is that i'm always part of a team even when i'm the sole developer, and the other team member is my past self (or my future self, depending on how you look at it) which counts toward "another person that has to read and understand the code"

I kind of do the same things, but it does depend on the level of complexity within the code. Much of what I write these days is for micro's and 1000 lines of code would be a rather big program where much of it is rather boring and run of the mill. None of this is the Linux Kernel so unless I do something cryptically because i resource limitations, I dont bother explaining much at all where it should be rather obvious what is happening. If I cant read the code and work out what is going on, i dont deserve to be working on it HAHAHA

However, when i contribute code to other projects, I am pretty liberal with comments on things that would be non obvious to anyone familiar with that code. Something like MyNumber = Ch->Level; I am not going to explain what Ch or Level are, because they are obvious to anyone who works with that code, but i would explain what I am doing with MyNumber if what followed was non trivial to the reader, with a couple of lines of comment above the function to explain its purpose and why I added it.

Hence my reply to the OP. How much hand holding does one require? Take a look at the comments in the Linux kernel. There is an expectation there that you actually understand something of the code before you work on it. Its not like the OP had any specific example of what he was complaining about, just a generic complaint about naming conventions and a lack of commenting. Perhaps, its more that he just lacks the skills and knowledge to be working on a piece of code in the beginning rather than there being a lack of commenting or naming convention.

I have worked smallish projects with half a million lines of code and yeah I have spent a few days reading the documentation and working through the code to understand it before I started to do anything and I am a hobby coder not a industry professional. Sometimes you have to put in a little more effort than plugging the blinky into the arduino and calling oneself a coder.

[PlainName]

Hence my reply to the OP. How much hand holding does one require?

I explained in the thread. One thing I do is a high level read of what the files are for, what the functions in it do, why they exist, so I know if this is the file I am looking for, or just getting a picture of wtf this project is. "Functions to implement double-ended linked lists" tells me a lot in 1.5 secs that spending 5 mins scanning the code or trying to make sense of stupid filenames probably wouldn't.

Comments are most use when not writing or changing code.

[tggzzz]

Hence my reply to the OP. How much hand holding does one require?

I explained in the thread. One thing I do is a high level read of what the files are for, what the functions in it do, why they exist, so I know if this is the file I am looking for, or just getting a picture of wtf this project is. "Functions to implement double-ended linked lists" tells me a lot in 1.5 secs that spending 5 mins scanning the code or trying to make sense of stupid filenames probably wouldn't.

Comments are most use when not writing or changing code.

I don't see why some people find that hard to comprehend!

I'll emphasise your point, again, by pointing out that a comment indicates what you don't need to look at.

[SiliconWizard]

Yes, that point was already made early in the thread.
To illustrate the point in maybe a slightly different light, think of writing code as you'd write text in a natural language, which Knuth and Wirth (among others) have been famous advocates of.
That basically means that comments should be used, IMO, as titles and footnotes when writing books and articles.

The "title" class of comments indicate what the following piece of code deals with. You have different levels of titles, like you have different levels of titles when writing text (entire text, chapters, sections, subsections, etc). Remove those titles entirely and any article or book will become nearly unreadable - and at the very least, very unpleasant to read. But organize your sections with a bit of common sense. Because conversely, A book with 1-sentence long sections or chapters would look annoying and ridiculous.

The 'footnote" class of comments detail a particular point in code that requires being developed a bit (so, more like the "how" category) when it's not obvious and when writing the code to make it more obvious (so not requiring any comment) would either be impossible, or unnecessarily heavy (and thus possibly more bug-prone). Just like you use footnotes when writing text, to detail a point that would be hard to detail in the main text itself, or make it unpleasant to read, or to follow the general line of thought. And so, just like with footnotes with natural language, use them sparingly. Again, imagine a book with a footnote at every other word, that would be a major pain to read and would show a clear problem in organizing one's thoughts and expressing them.

I've noted that there was some exxageration too in the discussion, and quite a bit of all-or-nothing statements, but that's not uncommon in any kind of discussion. For instance, about self-explanatory identifiers. Which are almost completely orthogonal to the question of commenting as described above anyway. For sure, use identifiers that are at least a bit descriptive, that helps readability a lot. But you don't need to make them 100-character long, that is exxageration and would be ridiculous.

[vk4ffab]

Hence my reply to the OP. How much hand holding does one require?

I explained in the thread. One thing I do is a high level read of what the files are for, what the functions in it do, why they exist, so I know if this is the file I am looking for, or just getting a picture of wtf this project is. "Functions to implement double-ended linked lists" tells me a lot in 1.5 secs that spending 5 mins scanning the code or trying to make sense of stupid filenames probably wouldn't.

Comments are most use when not writing or changing code.

While these are things you do, when it comes to code downloaded from the internet, its a lottery. Much of what gets written is about solving a problem that the author has, it was never meant for an end user or corporate client. How they go about it is their business and if they write a pile of crap that is impossible to understand the solution is simple, write your own code from scratch. And my comments have all been about addressing the 3 main points you make in your OP.

Why does no-one write comments any more? Not even just something to say what the function is meant to do, And variables! Really, do babies die or something if you let on WTF a variable is about?

As I stated in my first comment, the audience for my code is me, no one else even if I share it because it might have utility to others. But its all on them to understand it if they want to do more with it than just compile and use. So again, if i am writing code to solve a problem I have, what do I owe anyone to provide any level of documentation? Or name all my variables and functions something other than A, B, C etc. If my code is crap and unreadable, just do not use it. So again, how much hand holding do I or other authors owe anyone? 

Cant comment for others, by my  naming conventions are all about me being able to understand things later MyFuntionDoesThis and MyVariableHoldsThat I tend to be quite verbose and only add comments when and where what I have written is non obvious or uses some cryptic way of doing things in C.

[tggzzz]

Yes, that point was already made early in the thread.
To illustrate the point in maybe a slightly different light, think of writing code as you'd write text in a natural language, which Knuth and Wirth (among others) have been famous advocates of.
That basically means that comments should be used, IMO, as titles and footnotes when writing books and articles.

The "title" class of comments indicate what the following piece of code deals with. You have different levels of titles, like you have different levels of titles when writing text (entire text, chapters, sections, subsections, etc). Remove those titles entirely and any article or book will become nearly unreadable - and at the very least, very unpleasant to read. But organize your sections with a bit of common sense. Because conversely, A book with 1-sentence long sections or chapters would look annoying and ridiculous.

The 'footnote" class of comments detail a particular point in code that requires being developed a bit (so, more like the "how" category) when it's not obvious and when writing the code to make it more obvious (so not requiring any comment) would either be impossible, or unnecessarily heavy (and thus possibly more bug-prone). Just like you use footnotes when writing text, to detail a point that would be hard to detail in the main text itself, or make it unpleasant to read, or to follow the general line of thought. And so, just like with footnotes with natural language, use them sparingly. Again, imagine a book with a footnote at every other word, that would be a major pain to read and would show a clear problem in organizing one's thoughts and expressing them.

I've noted that there was some exxageration too in the discussion, and quite a bit of all-or-nothing statements, but that's not uncommon in any kind of discussion. For instance, about self-explanatory identifiers. Which are almost completely orthogonal to the question of commenting as described above anyway. For sure, use identifiers that are at least a bit descriptive, that helps readability a lot. But you don't need to make them 100-character long, that is exxageration and would be ridiculous.

Those are useful analogies, insofar as any analogy is useful.

Too many people think (and I use that word loosely) along these lines:

• I've had to deal with crap code
• that code has had crap comments and maliciously complied with coding standards
• such crap comments are worse than useless
• therefore comments are crap
• therefore comments should be removed

The fallacy is obvious, when you think about it.

In my experience, code with good comments doesn't need to be changed when it is used. A good comment indicates thought, and that is reflected in the code quality.

[PlainName]

That basically means that comments should be used, IMO, as titles and footnotes when writing books and articles.

That's a good take on it, yes 

[PlainName]

While these are things you do, when it comes to code downloaded from the internet, its a lottery.

Oh, you noticed what this thread is about after all!

As I stated in my first comment, the audience for my code is me ...

No problem with whatever you want to do for youself. Some people like a spotless and tidy worktop where others are unable to see the mess they leave behind and are forever searching for tools that are 'somewhere'. But whatever floats your boat is between you and your keel.

... no one else even if I share it because it might have utility to others. But its all on them to understand it if they want to do more with it than just compile and use. So again, if i am writing code to solve a problem I have, what do I owe anyone to provide any level of documentation? Or name all my variables and functions something other than A, B, C etc. If my code is crap and unreadable, just do not use it.

Well, some people like to be helpful and others don't give a toss. "I would like to make this a painless experience if I can" vs "fuck 'em, it's free", perhaps. Again, whatever floats your boat, but now the material of your keel is common knowledge.

So again, how much hand holding do I or other authors owe anyone?

'Owe'? Nothing, nada, zero, zilch. But an enlightening question.