It literally takes zero effort to type extra characters that conveys a meaningful function name, or a variable name.
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.
After a few years of continuing development the comments rarely say anything meaningful about the details of the code as it is today.
QuoteAfter 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.
QuoteAfter 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.
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.
It literally takes zero effort to type in a program. You are talking the mechanics, which is typically thought-free.
/*
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 );
}
/*
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 );
}
And I bet none of you variable names would tell me why it is there and how it should be used.
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.
Why would you spontaneously write code if you don't know the problem domain you are trying to solve?
So instead of writing code like this:
QuoteWhy 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.
QuoteIts 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.
QuoteIts 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.
In contrast, I have 40 years of actual experience that is is better than nothing. So there
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?
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.
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"
Hence my reply to the OP. How much hand holding does one require?
QuoteHence 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.
QuoteHence 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.
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?
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.
That basically means that comments should be used, IMO, as titles and footnotes when writing books and articles.
While these are things you do, when it comes to code downloaded from the internet, its a lottery.
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?