41–50 of 50 posts
//// These lines are a very simple way to enable feature X on your machine:
// obscure.thing=false
// someVar = "probablyAthing";
In the “Why” vein, some of the most important comments are “Why I made the compromises I made” aka “Why this looks dumb but is actually for the best” comments. They can prevent someone, including myself, from undergoing a timely rewrite of strange or bad looking code before inevitably hitting the same wall I hit previously.
Bang on. This practice has changed in the hosted, PR-based collaboration world. Instead of embedding this kind of thing in the source itself, it's written up in these constructs that exist outside. Then they go missing or are just undiscoverable, at least until it's too late.
This isn't as easy as I'd like, so I don't do it as much as I'd like. It's interesting to contemplate what sorts of UIs could make it easier.
At one point I distinctly recall github web UI for a commit showing you what PR(s) the commit was in -- but I'm having trouble reproducing that now, so maybe it no longer does? Or maybe i am confused and imagined it.
Earlier quoted context omitted.
The is not the natural state of things. That's also not the original state of things. For the decades that software engineering has existed, people have been busy migrating more and more information from offline in a different context into inline right at the code. Every single one of those times, people have experienced huge gains on the quality of the resulting comments, with moderate gains on project organization…
Different context meaning random chats and mailing lists, not an integrated system like Google Docs or Microsoft Word.
People have not spent those decades doing nothing. They tried a huge diversity of stuff.
Earlier quoted context omitted.
Bang on. This practice has changed in the hosted, PR-based collaboration world. Instead of embedding this kind of thing in the source itself, it's written up in these constructs that exist outside. Then they go missing or are just undiscoverable, at least until it's too late.
I quite often try to investigate those constructs before changing code I am not familiar with. Look at `git blame` to figure out commit(s) that touched the code. Try to figure out what PR they were part of to read the PR description. This isn't as easy as I'd like, so I don't do it as much as I'd like. It's interesting to contemplate what sorts of UIs could make it easier. At one point I distinctly recall github web…
It's also not unique to something like github. It was still possible to lose context when we used to email patches around. But I'm certainly encountering it more now, because I really do think the behavior has been influenced by the tooling. PRs are great, but in a case like this ("it looks dumb but it's not") the notes really ought to be inline. It's not practical to encourage a protocol wherein, upon every encounter with something fishy, we go traipsing all over trying to find out if someone, somewhere, sometime explained it.
I think my general point is that source management isn't the ideal place for the "whys" of things.
Earlier quoted context omitted.
I quite often try to investigate those constructs before changing code I am not familiar with. Look at `git blame` to figure out commit(s) that touched the code. Try to figure out what PR they were part of to read the PR description. This isn't as easy as I'd like, so I don't do it as much as I'd like. It's interesting to contemplate what sorts of UIs could make it easier. At one point I distinctly recall github web…
Yes, it's a lot of work, and it's very possible to just lose that information, even if you are committed to sticking with the platform. It's also not unique to something like github. It was still possible to lose context when we used to email patches around. But I'm certainly encountering it more now, because I really do think the behavior has been influenced by the tooling. PRs are great, but in a case like this ("i…
In the present case where it is very hard to track, ok. Of course we don't want to be forced to "go traipsing all around", and often won't bother if that's what it takes.
But comments are not a great place for it either. They can take up space, make source files harder to read as a whole (interupting your flow when you don't need them).
And a comment in source code is a commitment (often unmet!) to keep them _up to date_ and matching the code they describe, as it changes (as OP mentions), when actually for "why"/motivation, point-in-time comments at a point of _history_ (or several points as it changes) would often be quite sufficient, without the maintenance burden.
A world where many (not all) can be kept out of band in the source management system, as point-in-time historical notes, rather than in the source code itself and where it is very easy to track them down in source management, to me seems actually ideal.
I realize of course that world is not quite what we've got.
But for instance, when I _do_ track down the actual relevant (eg) PR's, especially aged ones, the _entire discussion history_ captured in them (possibly multiple PRs and commits over time) can often be _super valuable_, to have that context that there is no feasible way to embed in source code comments. Comments themselves are never going to be as good as we want, and we often end up doing "code archeology" regardless, what if it were super easy and frictionless to do?
I really wish (eg) github spent more time on UX to make this history easily followable without all the "traipsing around". But apparently there is not customer demand?
You all would hate my code, and that's okay. Why? Because I do everything that is suggested, save one: I leave what comments in. For some reason, it is easier and quicker for me to understand English prose than code, even if the code is simple. That includes checking the actual code after reading the comment to see if it matches; having a target for the code makes it orders of magnitude easier to read for me. That sa…
For example, if there's a feature around replies, I may put #replies in the key places in the code. If some code takes part in generating replies.html, I might put "#replies.html" as a comment.
A lot of my procedures have comments with alternative names aliased underneath:
sub SqliteQueryHashRef { # $query, @queryParams; calls sqlite with query, and returns result as array of hashrefs
#sub SqliteGetHash {
#sub SqliteGetHashRef {
#sub SqliteGetQueryHashRef {
#sub SqliteGetQuery {
#sub GetQuery {
#sub GetQueryAsHash {
#sub GetQueryAsArray {
#sub GetQueryAsArrayOfHashRefs {
BTW, if you only put a space after the procedure name in its definition, its much easier to search for.
In the “Why” vein, some of the most important comments are “Why I made the compromises I made” aka “Why this looks dumb but is actually for the best” comments. They can prevent someone, including myself, from undergoing a timely rewrite of strange or bad looking code before inevitably hitting the same wall I hit previously.
In the “Why” vein, some of the most important comments are “Why I made the compromises I made” aka “Why this looks dumb but is actually for the best” comments. They can prevent someone, including myself, from undergoing a timely rewrite of strange or bad looking code before inevitably hitting the same wall I hit previously.