Describing the what also helps when you dabble in a new technology or little-used technology. It helps to explain to yourself what you’re doing and it helps in onboarding. “Hey, newbie, there’s a function in XYZ module that’s extensively documented. Look there for guidance.”
Unless you’re working with people who are too smart, then sometimes the code only explains the how. Why did the log processor have thousands of lines about Hilbert Curves? I never could figure it out even after talking with the person that wrote it.
I don’t code, at best I script. I’m a sysadmin, not a dev, so I play around in PowerShell mostly.
I just started to naturally do all of this. Not because I was taught to, but because I’ve written too many scripts that I later looked at, and thought, WTF is going on here… Who tf wrote this? (Of course it was me)…
So instead of confusing my future self, I started putting in comments. One at the beginning to describe what the file name can’t, and inline comments to step me through what’s happening, and more importantly why I did what I did.
The sheer number of comments can sometimes double the number of lines in my script, but later when I’m staring into the abyss of what I wrote, I appreciate me.
Have reviewed 16 year old code for a very well known company in the last week with this exact comment peppered throughout, alongside delightfully helpful comments like:
// do not delete or change this it just works
// TODO temporary fix added 12/09/11 to fix incident must be removed ASAP
// CAUTION this returns false here instead of true like it normally does, not sure why
// if true then matched to valid account not is true
The person who changed the code, it’s just ordinary maintenance. The comments may not execute, but I submit they are as much a part of the program as the executable code. Maybe over time those comments are condensed, or even removed; no different than any other refactoring or cleanup.
Snapmaker Luban is amazing with its help messages.
Every setting in this 3D slicer is completely explained how the setting works, what the different options are, with pictures and even what every option is the most optimal in whatever situation.
Too bad that it isn’t the best program unless you have a Snapmaker, and even then…
plenty of APIs in Java have documentation like that and it is worst when I read the documentation in order to find out the definition of the nouns and verbs used there and then it is just like that
Sometimes I think after i retire, I should teach. In the hopes that i could inspire people to write good code, instead of a lot of the garbage i see in the industry. This comment makes me sad.
I just want to be clear, this was like highschool cs classes. I took things a bit more seriously in college.
I never wrote messy code or illogical code, or any code that didn’t work. We were learning C++ in those days and if you know anything about C++, you can basically cram an entire program into a single line. You can also do some shorthand stuff for calculations and updates to variables… So while the class was instructed to use whitespace and comments and update variables like “var = var + #” I would do var += #… I wouldn’t comment it, mainly out of hubris.
I was pretty good at it but I was lazy as all hell with it.
I feel like I am going to have to do the same thing in the end, to get my hand-over accepted.
Should I just copy the line of code and make a comment next to it with:
<span style="font-style:italic;color:#969896;">// It does <paste line of code>
</span>
Not every. The quick, very-low effort ones, I just leave.
Why:
I saw another post with “Anti Commercial AI License”, then wen on to read the license and went, “Neat!”.
It makes it easier for anyone to decide what to do if they want to use my comment/post (in cases where it actually has something useful)
It makes life just a bit harder for people data-mining for AI
That way, some data entry worker will probably ask for a raise and probably even get it and maybe some entrepreneur going “AI everywhere!” will think twice.
Or there will be a chatbot spouting “Anti Commercial AI License” or “CC By-NC-SA” in their answer text, which would be hilarious.
For now, I have just saved it in my clipboard application, so I copy-paste.
When it goes out of history, I just open a file, where I have saved it and copy from there. So it’s pretty crude.
I was hoping that either the KDE Social web interface would add a “Signature” feature or I would pick some Lemmy application that would allow that, but for now it’s just this.
Perhaps, if I feel like it’s being too frequent, I may set a compose key for it.
Hm. The first hit on DuckDuckGo is a single entry for a guy and all it says is Contact the Business Inquiries.
You would think a better solution to this problem would be to put a message on that page stating that if you’re a McAfee user looking for information about SQLite files in your temp folder, to call the McAfee support line.
If that information said something like “McAfee users concerned about temp files, call (800) 123-4567”, then yes. Did I suggest anything more than that? No. 🙄
How is that irrelevant? The folder is literally called Temp. Doesn’t matter anything else. You said, and I quote, “The kinds of people who need this message, you would have lost the second you said “temp files”.”
Obviously not sure, given where the files were located. 🤦♂️
And of course they didn’t know what the files were for; probably why they went searching for it, and eventually found the contact info for Richard Hipp.
Me thinks you just want to shit on people for no other reason than to make yourself feel superior to them. 👏 Congrats!
Assuming that they went out to look for it, and didn’t just poke google with (“sqlite hacked my computer”) until they found a phone number.
If they had gotten the phone number for a company called Super Queasy Lite and Easy/SQLitE instead of the developers, the company might well have received the calls instead.
Assuming that they went out to look for it, and didn’t just poke google with (“sqlite hacked my computer”) until they found a phone number.
and how in the world did they know to type the word “sqlite” in. Dude, the files are in the temp folder. The only way they know the name “sqlite” is if they literally visited the folder and looked there.
Error message? McAfee can’t write to the drive because it’s full of photos of their grandchildren and dogs, so it clicks up “can’t write to c:\temp\sqlite_arcane_computer_magic.log: Disk is full”, and it goes from there?
You do realize that these people were looking up contact info from a company they found because they were … wait for it … looking at files inside the temp folder … otherwise known as … are you sitting down? You really should sit for this … temp files!
Imaging that. 😳 🤣
By the way, I worked technical support for my local dialup ISP, Adobe, Best Buy (before they were called Geek Squad), and OnStar.
looking at files inside the temp folder … otherwise known as … are you sitting down? You really should sit for this … temp files!
The point OP is making is that those people would not put 2 and 2 together to understand that the files they were looking at are called temp files, just because that’s the folder they found them in. They may not even remember the name of the folder, only that it contains a bunch of files with a prefix they’re now googling.
Not sure why I’m bothering explaining this to you, the way you responded makes you look absolutely insufferable, but maybe someone else who comes across this will find it useful.
Yup, you found the developer. That’s his phone number.
It’s not exactly a new change either. In 2006 people weren’t going to the specific page from duckduckgo, they were probably finding the sqlite homepage, and then tracking down the contact info.
20 years later it’s probably better to maintain consistency with the prefix than to change it even if it’s weird.
So, sure that might work. More likely they forgot this bit is even here on account of it being 20 years old.
Also, never doubt the persistence of a sufficiently motivated and impatient user. I don’t think needing to read something has ever stopped one.
You can literally put animated flaming text and people will click right past.
During my time in a call center people would often call for invoices or messages they received. Most of my work there was reading the thing together with them. Nothing more was necessary, I just read alound their itemized invoice that they had received and it would solve their problem.
Click through pop-ups are even worse in this regard. I myself usually just automatically click No before I understand what just happened.
I worked for a developer at a Web hosting company for a while. I really wish my story about flaming text wasn’t true, and that the words weren’t “permanent unrecoverable data loss”, and the audience wasn’t internal support technicians.
Gotta have a way to delete a vps, and there’s only so much you can do to get someone to check that they have the right one.
The way I understand the users didn’t necessarily realize McAfee is responsible, just that a bunch of sqlite files appeared in temp so they might not connect the dots here anyway. Or even know McAfee is installed considering their shady practices.
Fair point about not knowing McAfee if involved. But at the same time, it beats having your dev getting phone calls at all hours because McAfee’s devs were to lazy to ready the source file and learn how to change the freaking prefix of the file.
I absolutely agree, and I too hate this stupid idea of “good code documenting itself” and “comments being unnecessary”.
I have a theory where this comes from. It was probably some manager, who has never written a single line of code, who thought that comments were a waste of time, and employees should instead focus on writing code. By telling them that “good code documents itself”, they could also just put the blame on their employees.
“Either you don’t need comments or your code sucks because it’s not self-documenting”
Managers are dumb, and they will never realize that spending a bit of time on writing useful comments may later actually save countless hours, when the project is taken over by a different team, or the people who initially created it, don’t work at the company anymore.
I’ve never had a manager that was even aware of the comments vs. no comments issue. If I ever had, I would have just told them that a lack of comments makes the original coder harder to replace.
Code should always by itself document the “how” of the code, otherwise the code most likely isn’t good enough. Something the code can never do is explain the “why” of the code, something that a lot of programmers skip. If you ever find yourself explaining the “how” in the comments, maybe run through the code once more and see if something can be simplified or variables can get more descriptive names.
For me, that’s what was originally meant with self-documenting code. A shame lazy programmers hijacked the term in order to avoid writing any documentation.
I don’t think they’re lazy, I think they’re not good writers. Not being able to write well is very common among programmers (not having to communicate with written language is one reason a lot of people go into coding) and in my experience the Venn diagrams for “not a good writer” and “thinks comments are unnecessary” overlap perfectly.
And isn’t it such a dangerous overlap! The coder whose writing (in their native language) is unclear, repetitive, convoluted, or hard to follow too often produces code with the same qualities. It’s even worse when the same coder believes “code is self-documenting” without considering why. Code self-documents with careful and deliberate effort, and in my experience, it is the really good writers who are most capable of expressing code in this way.
Its definitely a balance. Good code shouldn’t need much commenting, but sometimes you have to do something for a reason that isn’t immediately obvious and that’s when comments are most useful. If you’re just explaining what a snippet does instead of why you’re doing it that way, there’s probably more work to be done.
Comment should describe “why?”, not “how?”, or “what?”, and only when the “why?” is not intuitive.
The problem with comments arise when you update the code but not the comments. This leads to incorrect comments, which might do more harm than no comments at all.
E.g. Good comment: “This workaround is due to a bug in xyz”
Bad comment: “Set variable x to value y”
Note: this only concerns code comments, docstrings are still a good idea, as long as they are maintained
In my opinion, it strongly depends on what you’re coding.
Low-level code where you need to initialize array indices to represent certain flags? Absolutely comment the living shit out of that. → See response.
High-level code where you’re just plumbing different libraries? Hell no, the code is just as easily readable as a comment.
I do also think that, no matter where you lie in this spectrum, there is always merit to improving code to reduce the need for documentation:
Rather than typing out the specification, write a unit/integration test.
Rather than describing that a function should only be called in a certain way, make it impossible to do it wrongly by modelling this in your type system.
Rather than adding a comment to describe what a block of code does, pull it out into a separate function.
Rather than explaining how a snippet of code works, try to simplify it, so this becomes obvious.
The thing with documentation is that it merely makes it easier to learn about complexity, whereas a code improvement may eliminate this complexity or the need to know about it, because the compiler/test will remember.
This does not mean you should avoid comments like they’re actively bad. As many others said, particularly the “why” is not expressable in code. Sometimes, it is also genuinely not possible to clean up a snippet of code enough that it becomes digestable.
But it is still a good idea, when you feel the need to leave a comment that explains something else than the “why”, to consider for a moment, if there’s not some code improvement you should be doing instead.
Hard disagree on your first point. Name the flags with descriptive name, move this initialisation to a function, and there you go, self-documented and clear code.
Hmm, maybe my opinion is just shit in that regard. I don’t code terribly much low-level, so I’m probably overestimating the complexity and underestimating the options for cleaning things up.
That was kind of just a random example, I felt like there were many more cases where low-level code is complex, but I’m probably basing this off of shitty low-level code and forgetting that shitty high-level code isn’t exactly a rarity either.
I’m with you but sometimes you don’t have the chance in low level. Max you can do is create local variables just so the bits you’re XORing are more obvious. And whenever you’re working with something where that’d be wasteful and the compiler doesn’t rid if it, you’re better off with comments (which you need to maintain, ugh)
Good code is self documenting as in you don’t need to describe what it is doing and it is clear to read. Whoever says that and isn’t just repeating what they heard understands that whenever you are doing something not explicit in the code it should be on a comment.
Workarounds and explaining you need to use this structure instead of another for some reason are clear examples, but business hints are another useful comment. Or sectioning the process (though I prefer descriptive private functions or pragma regions for that).
It also addresses the hint that the code should be readable because you’re not going to have comments to explain spaghetti. Just a hint, doesn’t prevent it. Others also said it, comments are easier to get outdated as you don’t have the compiler to assist. And outdated comments lead to confusion.
I follow these simple rules and encourage my colleagues to do so
If I’m just shuffling jsons, then yes, the code should be self documented. If it’s not, the code should be rewritten.
If I implement some complex logic or algorithm, then the documentation should be written both to tests and in the code. Tests should be as dull as possible.
If I write multithreading, the start, interruption, end, and shared variables should be clearly indicated by all means that I have: comment, documentation, code clearness. Tests should be repeated and waits should not be over 50ms.
What they mean is that the variable names and function names are documentation.
For example changing “for( i in getList() )” to “for( patient in getTodaysAppointments() )” is giving the reader more information that might negate the need for a comment.
I actually agree that “good enough” code can be self-documenting, but it isn’t always enough to achieve my goal which is to make the code understandable to my audience with minimal effort. With that goal in mind, I write my code as I would write a technical document. Consider the audience, linear prose, logical order, carefully selected words, things like that… In general, I treat comments as a sort of footnote, to provide additional context where helpful.
There are limits to self-documenting code, and interfaces are a good example. With interfaces, I use comments liberally because so many of the important details about the implementation are not obvious from the code: exactly how the implementation should behave, expected inputs and outputs under different scenarios, assumptions, semantic meaning, etc. Without this information, an implementation cannot be tested or verified.
Have you ever worked in a place where every function/field needed a comment? Most of those comments end up being “This is the <variable name>, or this does <method name>”. Beyond, being useless, those comments are counter productive. The amount of screen space they take up (even if greyed out by the IDE) significantly hurts legability.
I get what you’re saying. Perhaps I just haven’t had too many variables and such that have had such comments. VsCode shows the comments on hover when you’re in other parts of the code base. Which makes most any comment useful because something that is obvious in one part of the code isn’t immediately obvious in another. Though, that necessitates making comments that actually help you figure that out.
I have worked on larger older projects. The more comments you have, the larger the chance that code and comment diverge. Often, code is being changed/adapted/fixed, but the comments are not. If you read the comments then, your understanding of what the code does or should do gets wrong, leading you on a wrong path. This is why I prefer to have rather less comments. Most of the code is self a explanatory, if you properly name your variables, functions and whatever else you are working with.
One example for self documenting code is typing. If you use a language which enforces (or at least allows, as in Python 3.8+) strong typing and you use types pro actively, this is better than documentation, because it can be read and worked with by the compiler or interpreter. In contrast to documenting types, the compiler (or interpreter) will enforce that code meaning and type specification will not diverge. This includes explicitly marking parameters/arguments and return types as optional if they are.
I think no reasonable software developer should work without enforced type safety unless working with pure assembler languages. Any (higher) language which does not allow enforcing strong typing is terrible.
What a time it must’ve been, being able to publish your phone number online without fear. Now you give it to any website and it’s sold straight away to advertisers. Making it public would be a nightmare.
I have my phone number on my personal website—never had any adverse consequences. In fact, the only two calls I’ve gotten have both been at my work number which isn’t on there somehow. One to ask a genuine question and one to give me 30 bucks in appreciation.
You don’t even need to make public yourself. City governments do it automatically, mostly if you’re a home owner. Other companies do it because they keep getting hacked.
Try it.
Go to your favorite search engine and type in your phone number (format it to look like a phone number). If you haven’t already gone through and had yourself removed from these types of sites, you’ll be appalled at what you find.
Forgive my ignorance. SQLite is a database software. Why would McAffee create lots of database files?
[Edit:] I’m not asking why a program needs to store data. I’m asking why that necessitates many files. One database file (or one per table) should be enough, right?
Sqlite is a great embedded database.
If you are storing lots and lots of information in a JSON file, CSV file, or coming up with your own serialisation… Chances are, sqlite is going to do it better.
I know loads of android apps use sqlite for storage. I’ve also managed to open quite a few programmes “proprietary” file format in sqlite.
The file also isn’t written sequentially, it’s stored in blocks (pages), where sometimes later data can be inserted in the middle (e.g. when data was deleted).
The program needs to store multiple temporary files (one per virus definition update, or scan results or whatever purpose).
It looks like they simply picked sqlite as a format because the data has a structured format and that way they leverage databases robustness, easiness to read and query the data.
The comment appears to be from 2006. Sqlite mightve had some limitations then that necessitated creating a new (temporary) database file as a subset of larger database for performance reasons or to allow multiple processes to read/write them and then consolidate data back into the single database.
Oh, I thought that the temp files were named by the user. If that’s not the case, that these are not databases created specifically by McAfee in the temp directory, then I’m not sure what the appropriate solution should be. Obscuring the file type and how the file is used from users is still a bad practice.
McAfee wrote a program that used the Sqlite library for database storage.
When going about its data storage business for McAfee’s program, the Sqlite library was storing files in C:\temp with prefixes like sqlite_3726371.
Users see that and get angry, and bug the Sqlite developers.
Now probably when initialising the Sqlite library McAfee could have given it the location of a directory to keep it’s temp files. Then they could have been tucked away somewhere along with the rest of the McAfee code base and be more easily recognised as belonging to them, but they didn’t.
So because of a bit of careless programming on McAfee’s part, Sqlite developers were getting the heat because the files were easily recognisable as belonging to them.
Because the Sqlite developers don’t have control of what McAfee was doing, the most expedient way to solve the problem was to obfuscate the name a bit.
Yeah, if it’s purely a Sqlite implementation detail to create temp files, that’s on them to own and fix. I thoroughly dislike that the files are obscured from users.
programmer_humor
Oldest
This magazine is from a federated server and may be incomplete. Browse more on the original instance.