Every line of code is always documented(mislav.uniqpath.com)
mislav.uniqpath.com
Every line of code is always documented
http://mislav.uniqpath.com/2014/02/hidden-documentation/
103 comments
"Code happens". In reality, there's code that should have been commented all the time and even in the best codebases. I don't think there's a coder in the world who hasn't had a time when he's looked back on a piece of code and just thought "what?". If you get in the habit of keeping a well documented git history, it's an invaluable resource. I find on top of these benefits, having to explain what changes I made also helps me make smaller and easier to understand commits, which also helps with summarizing releases, finding commits where bugs were fixed or introduced, and so much more. A well documented git history is the closest thing to a time machine you can get.
Should these things happen? No. Do they happen? All the freaking time.
Should these things happen? No. Do they happen? All the freaking time.
What? No, it's got nothing to do with commenting. It's to do with basic code design: put your stuff in functions. A line like that should have been in a function to start with, and it should have been caught during a code review or as common sense by the committer before he even committed.
Agreed. Maybe it's in some insane tight loop where you don't want a function call - in which case you comment it. My rule is that if there's something I have to put in the code that's out of the ordinary, I comment to explain.
The point of the article has nothing to do with the code snippet. My point has nothing to do with the code snippet. It's just about code in general, and it's never as easy to understand as you want it to be.
basic code design: put your stuff in function
Aye, and with intention revealing names!
http://c2.com/cgi/wiki?IntentionRevealingNames
Also: http://c2.com/cgi/wiki?LawOfDemeter
Aye, and with intention revealing names!
http://c2.com/cgi/wiki?IntentionRevealingNames
Also: http://c2.com/cgi/wiki?LawOfDemeter
Thanks for your words of defense, etler. A lot of the criticism of my original post was valid, though, so I addressed it by rephrasing and stressing out that code quality still matters: https://github.com/mislav/mislav.github.com/commit/e07907966...
You were right, however, that the post was never about code quality or code comments. It was only about "history's great, yo; here's what you can do with it".
You were right, however, that the post was never about code quality or code comments. It was only about "history's great, yo; here's what you can do with it".
Honestly they should just have a comment:
// This triggers layout. Needed for some browsers.
But agreed that you shouldn't require relying on history for this context. It's bad news. Yes code happens, but it should be obvious what it does (via clear code) and why (via comments as needed).
// This triggers layout. Needed for some browsers.
But agreed that you shouldn't require relying on history for this context. It's bad news. Yes code happens, but it should be obvious what it does (via clear code) and why (via comments as needed).
I was recently watching a talk given by Rich Hickey where he talks about serialization formats and how they can have all their metadata in-band or have to depend on out of band information. The latter situation is where bugs can be introduced.
The example in the original post relies heavily on out of band documentation. Your suggestion of an intention revealing function name puts the same info in-band.
One should always ask themselves: Does my code depend on out of band information? If so, can we correct this?
The example in the original post relies heavily on out of band documentation. Your suggestion of an intention revealing function name puts the same info in-band.
One should always ask themselves: Does my code depend on out of band information? If so, can we correct this?
That may be true for the given example, but it doesn't work that way for all the nuances of code that come up. For one thing because English wording has ambiguities, and for another because there are so many concerns with some cross-cutting each other that you can only break things down into atomic functions to a certain degree.
I think the overall point of the article rings very true: great VCS habits pay dividends over time regardless of how well-crafted the code itself is.
I think the overall point of the article rings very true: great VCS habits pay dividends over time regardless of how well-crafted the code itself is.
Way to miss the point completely.
But he is actually right: when dealing with obscure implementation details, the best thing to do is to encapsulate it properly, the minimum is to comment it clearly, and ideally detailed explanations should be written in the commit message.
Having a detailed code history isn't in any way an excuse to leave obscure code as is. If you have time to document it, you have time to make the code right.
Having a detailed code history isn't in any way an excuse to leave obscure code as is. If you have time to document it, you have time to make the code right.
Of course he is right. But he still completely missed the point of the article, which was not to defend writing or keeping code that is not self explaning. I mean, it's the goddamn premise of the article that you happen to stumple upon a piece of code that's less than perfect! The example in the article describes a situation in which you find a piece of code someone else wrote and you are unsure of what it does or why it's there.To even begin contemplating improving the code, you first have to understand it. The article is about how you can do that with Git logs. So that once you've done that you may proceed to improve it. And yes, extracting it into a well-named method is probably a good way to do that. But that, as I hope we've established, is besides the point.
The premise of the article is that you happen to stumble upon a messy piece of code and that the explanations related to it might be located into the source history. Yet the only reason why these explanations would actually be there is that someone would have enforced doing that as a rule. And the point of the counter-argument is that before enforcing this rule this same person should be enforcing a rule saying that writing messy code like that is prohibited.
In short, maintaining a clean code base has always higher priority than maintaining a clean log.
In short, maintaining a clean code base has always higher priority than maintaining a clean log.
jesus christ
http://lsolum.typepad.com/legal_theory_lexicon/2003/09/legal...
this article is about recommendations of what to do ex post once a comment-less line of code has been committed in the past that you need to understand. arguments about ex ante things such as how it got there in the first place and how to prevent it from happening is completely orthogonal to the point of the article.
http://lsolum.typepad.com/legal_theory_lexicon/2003/09/legal...
this article is about recommendations of what to do ex post once a comment-less line of code has been committed in the past that you need to understand. arguments about ex ante things such as how it got there in the first place and how to prevent it from happening is completely orthogonal to the point of the article.
Strong disagree. The article is about recommending and making ex post use of a policy for good commit messages. The point argued is in favor of a future rule for good commit messages. Therefore it is very reasonable to suggest a superior rule for the future.
As rymohr indicated, the author of the code given as example is actually the author of the article himself:
https://github.com/madrobby/zepto/commit/3d92f20966aa02dee82...
Which means the OP genuinely thinks that commits like this one are good practice, and the purpose of the article is to show how to deal with it.
Yet as it was argued above, commits like that should never happen in the first place.
https://github.com/madrobby/zepto/commit/3d92f20966aa02dee82...
Which means the OP genuinely thinks that commits like this one are good practice, and the purpose of the article is to show how to deal with it.
Yet as it was argued above, commits like that should never happen in the first place.
And it didn't. This was the commit that actually happened: https://github.com/madrobby/zepto/commit/2ed0123eaddc023a857...
Notice the code comment. I took it out for the example in the blog post to illustrate how we would deal if there was never a code comment in the first place.
Notice the code comment. I took it out for the example in the blog post to illustrate how we would deal if there was never a code comment in the first place.
That's like saying that a "counter-argument" to wearing a seatbelt is that drivers shouldn't be getting into accidents in the first place. Yes, it would be nice if all code was well-commented and well-factored with well-named functions, classes and variables, and we should all strive to make code like that. And if that never failed, then perhaps we wouldn't need any other best practices or rules to help us along.[1] But we all know the real world is not like that. We need all the help we can get. Having good practices for writing good code is not, I repeat not an argument against having good practices for commit comments. You make it out to be an either/or proposition. It's not.
From what I've seen in the article, the point was to present ways of getting documentation out of commit messages, not implying that they should be used for documenting (which I would disagree with, too).
I think he got the point. Just that the article is predicated on something incredibly stupid: someone writing a line of code that, to probably most people other than the author, is useless and incomprehensible. I think it's great that the author wrote a detailed explanation in the git commit message, but it's absolutely not enough. That piece of code needs at least a one-line comment there, full stop.
I think the article as a whole is great in that it taught me some things you can do with git that I didn't know before (well, stuff I figured was possible, but didn't know the magical incantations). But it's hard to start reading it and really appreciate all that when the initial premise for explaining all that stuff was... well, someone having a severely bad day when it comes to writing clear code.
I think the article as a whole is great in that it taught me some things you can do with git that I didn't know before (well, stuff I figured was possible, but didn't know the magical incantations). But it's hard to start reading it and really appreciate all that when the initial premise for explaining all that stuff was... well, someone having a severely bad day when it comes to writing clear code.
> That piece of code needs at least a one-line comment there, full stop.
From my experiences in the real world and from reading comments here, I think there are a lot of people that disagree with that assertion, and it kind of makes me wish I worked in a field where I don't feel like I'm going insane on such a regular basis.
From my experiences in the real world and from reading comments here, I think there are a lot of people that disagree with that assertion, and it kind of makes me wish I worked in a field where I don't feel like I'm going insane on such a regular basis.
It seems that this was the only instance of its use in the whole codebase. I certainly agree that a comment should have been placed there, and of course creating a function would be the most idealistic solution. But I think that, without knowing the specific context, it is hard to say whether creating a function would have been an improvement or detriment to the code -- especially considering it is just a single line of code.
This is probably not a popular view, but I don't really understand why comments are viewed by some people as a bad thing. I agree that useless, redundant comments are not helpful. But that doesn't mean all comments are useless. I don't agree that well-written code never needs comments either. Reading the code tells you what it does. It doesn't always tell you why it's there.
Digging through version control comments seems to me a last-ditch effort to figure out what some code is doing. If the project had any significant history you could be digging through hundreds of commit messages. Why not just put a 1-liner comment above that line and save every subsequent developer the hassle of wondering what the heck that seemingly useless line does..?
Digging through version control comments seems to me a last-ditch effort to figure out what some code is doing. If the project had any significant history you could be digging through hundreds of commit messages. Why not just put a 1-liner comment above that line and save every subsequent developer the hassle of wondering what the heck that seemingly useless line does..?
Exactly this, with the addition that there are actually three things I want to see when reading code, only one of which can often be elegantly expressed without comments.
I usually want to see (1) what the code does (2) what the code is intended to do and (3) why the code is intended to work that way. Usually only the first can elegantly and most easily be expressed in code.
For instance, I read a performance-critical function that would stop processing data and return early in an obscure corner case, but performed better than the best way I could think of to handle the obscure corner case. There were at least 3 possibilities: (1) the author made a mistake (2) for reasons I couldn't see, the corner case was impossible or (3) for reasons I couldn't see, the consequences of mishandling the corner case were never as bad as I thought they could be and the performance gain was worth it. I had to look up the revision history, call up the author and ask him which it was. It turns out the author had missed the corner case, but I try to as rarely as possible assume I'm smarter/more insightful than the original author.
I usually want to see (1) what the code does (2) what the code is intended to do and (3) why the code is intended to work that way. Usually only the first can elegantly and most easily be expressed in code.
For instance, I read a performance-critical function that would stop processing data and return early in an obscure corner case, but performed better than the best way I could think of to handle the obscure corner case. There were at least 3 possibilities: (1) the author made a mistake (2) for reasons I couldn't see, the corner case was impossible or (3) for reasons I couldn't see, the consequences of mishandling the corner case were never as bad as I thought they could be and the performance gain was worth it. I had to look up the revision history, call up the author and ask him which it was. It turns out the author had missed the corner case, but I try to as rarely as possible assume I'm smarter/more insightful than the original author.
Exactly this. I found myself thinking WTF as I read the article. Maybe I'm showing my age, but the project I just switched from (and still have to consult on from time to time) was started in the late 90's and probably won't be retired for at least 10 more years. I have found myself not just looking through version control history to understand the change history of a file to find a bug, but tracking it over multiple version control systems as the project matured.
> This is probably not a popular view, but I don't really understand why comments are viewed by some people as a bad thing.
Probably the same people think that well-written code does not need comments at all. That may be so, but well-written code is hard to come by. While this rock-star macho attitude is aplenty.
Probably the same people think that well-written code does not need comments at all. That may be so, but well-written code is hard to come by. While this rock-star macho attitude is aplenty.
And to be perfectly honest, well written code might not stay well written as project circumstances change. Thus, documentation that can be updated often makes life easier going forward.
And even worse, sometimes code can't be well-written once you start interfacing with third party software with quirky shenanigans. We got quite some comments flying around such as "In case you are wondering: yes, this call is necessary, or this and that situation will propagate through these two libraries and break with this obscure, unhelpful error message. If you ever change this, look at those documentation files for unobvious, scary testcases to look at".
> Probably the same people think that well-written code does not need comments at all. That may be so, but well-written code is hard to come by. While this rock-star macho attitude is aplenty.
Not only that, but I speculate that those holding such opinions are usually young, well above average programmers who therefore work exclusively on brand new projects - many of them have literally never experienced the nightmare of maintaining and extending some crap code written in the most clever and obscure way possible by someone similar to themselves. Hell, a lot of them likely don't stick around long enough to make major modifications to their own code.
Not only that, but I speculate that those holding such opinions are usually young, well above average programmers who therefore work exclusively on brand new projects - many of them have literally never experienced the nightmare of maintaining and extending some crap code written in the most clever and obscure way possible by someone similar to themselves. Hell, a lot of them likely don't stick around long enough to make major modifications to their own code.
Yes, it's easy (and fun) to write clever code that is unmaintanable. It's much harder to write code that is simple. To me, people who can do that day in, day out are true rock-stars of programming.
I think it has something to do with the idealistic view of "pure, well-written" code. There's something appealing about a code base consisting of only code, not comments. But in my very subjective experience, I've noticed that the more programming experience people have under their belts, the more likely they are to appreciate commenting as a tool among other tools to make your code readable.
I think that's a very good point and it seems to me the spirit of that argument is "write code that is so clean that it doesn't need comments." Or the inverse of that could be "if your code needs a lot of comments then it probably isn't very clean."
So I think that is a good mentality in as much as it keeps you thinking and writing clean code. But, I think it's also rather presumptuous to assume everything will be clear to others. Also as you say - once you've had to stick around and maintain a few applications, you really appreciate a thoughtful programmer who put in some comments that saved you a few hours. And you start to loath the rock-star who came in for 6 months and wrote a bunch of code using the fad-of-the-moment design pattern without commenting anything.
So I think that is a good mentality in as much as it keeps you thinking and writing clean code. But, I think it's also rather presumptuous to assume everything will be clear to others. Also as you say - once you've had to stick around and maintain a few applications, you really appreciate a thoughtful programmer who put in some comments that saved you a few hours. And you start to loath the rock-star who came in for 6 months and wrote a bunch of code using the fad-of-the-moment design pattern without commenting anything.
Is that actually a widespread view? I though at least post-1970 or so, it was pretty standard practice to comment liberally. Going all the way to Knuth-style literate programming hasn't caught on, I'll admit, but I didn't think wall-of-code was widely admired anymore either.
It's been a while since I've seen a discussion on code comments here on HN but I have noticed in the past that there's a vocal group who are fairly passionate against code comments. I was actually expecting a wave of downvotes to my original comment.
I disagree with "liberally", as there's a cost associated with commenting (they have to be maintained and people have to spend time to read them), but I'm certainly of the opinion that judiciously commenting is very useful.
But why would you only comment this in the git history?
Why on earth wouldn't you place this explanation in a comment preceding the line of code itself?
One of the best things I ever learned in programming is that you shouldn't write code to be executed -- you should write code to be read and understood by other people.
It's going to take me forever to read your file and understand what's going on if I have to do a git blame on every other line.
Just use short purpose-based commit messages (fixes a bug where..., so now...), and then put the actual why behind the implementation in the source code comments itself!
Why on earth wouldn't you place this explanation in a comment preceding the line of code itself?
One of the best things I ever learned in programming is that you shouldn't write code to be executed -- you should write code to be read and understood by other people.
It's going to take me forever to read your file and understand what's going on if I have to do a git blame on every other line.
Just use short purpose-based commit messages (fixes a bug where..., so now...), and then put the actual why behind the implementation in the source code comments itself!
In my opinion, the full explanation is too long to be put as code comment, but is just right as the commit message. The best way is to keep the commit message, but add a short comment like:
Basically, for simple code with unclear purpose, I'd go with short comment in the code plus full explanation in the commit message. For hard-to-read code with complicated logic, I'd go with long comment in the code. Or refactoring.
Ticket description, commit message, code comment, and the code itself are all necessary to keep the codebase "documented".
// Hack to trigger layout change in latest Mozilla
Basically, for simple code with unclear purpose, I'd go with short comment in the code plus full explanation in the commit message. For hard-to-read code with complicated logic, I'd go with long comment in the code. Or refactoring.
Ticket description, commit message, code comment, and the code itself are all necessary to keep the codebase "documented".
If the codebase is associated with a reasonably stable bug-tracker, I'd also put a bug # or a URL in the source comment if it's something nonobvious that is important for future maintainers to be aware of, but considered too long to document inline (if it's purely of historical interest, then yeah, leave it to the VCS history). Or a link to an archived mailing list discussion, or a CVE id, or some kind of hint.
I'm genuinely curious -- what is the thinking behind "too long to be put as code comment"? I've never heard that before.
It's not like we're conserving paper. And syntax highlighters helpfully give comments different colors so you can skip over them while reading.
Personally, I've never once wished that a particular piece of code were less commented, but there are hundreds if not thousands of times I've wished that there was more explanation, or any at all.
It's not like we're conserving paper. And syntax highlighters helpfully give comments different colors so you can skip over them while reading.
Personally, I've never once wished that a particular piece of code were less commented, but there are hundreds if not thousands of times I've wished that there was more explanation, or any at all.
Comments are frequently out of date with the code that they're describing. This tendency is somewhat linear with the length if a comment and therefore longer comments will be more incorrect, more quickly. I'm not being facetious, this is a readily observed phenomena.
Long comments get out of date quickly because it isn't clear how the comments relate to the code on a quick scan. In this case, you want a quick note as to why the code is there. You can add external references if needed.
You don't want to make someone who is editing code stop to think about how it affects the comments.
You don't want to make someone who is editing code stop to think about how it affects the comments.
>You don't want to make someone who is editing code stop to think about how it affects the comments.
What's the point of comments then if your general rule is that it should be fine to edit code without changing the comments?
What's the point of comments then if your general rule is that it should be fine to edit code without changing the comments?
> What's the point of comments then if your general rule is that it should be fine to edit code without changing the comments?
Not without changing the comments. Without stopping to ponder how two paragraphs of comments fit into the code changes. The comments (aside from API documentation) should annotate the code, not the other way around.
Not without changing the comments. Without stopping to ponder how two paragraphs of comments fit into the code changes. The comments (aside from API documentation) should annotate the code, not the other way around.
Exactly.
My problem is that usually the people who neglect to write a comment in the code, also neglect to write meaningful commit messages. Usually it's just "fixed the layout bug" or something like this, along with a bunch of other unrelated changes all squeezed into one commit.
My problem is that usually the people who neglect to write a comment in the code, also neglect to write meaningful commit messages. Usually it's just "fixed the layout bug" or something like this, along with a bunch of other unrelated changes all squeezed into one commit.
what version control gives you (as a last resort) is a sense of how a change fit into a specific pattern of changes. That's really all you can rely on it for. That's really helpful when trying to track down what broke when, but if it is a routine task, you are in a world of trouble.
I concur.
I've worked in enterprise. If your team relies on a centrally administered source control, then you can be in a world of pain if the central team decides to switch tools (and when this happens moving your revision history comments to the new system will never be considered important, if even possible).
Keep important things in the code. That's my experience.
I've worked in enterprise. If your team relies on a centrally administered source control, then you can be in a world of pain if the central team decides to switch tools (and when this happens moving your revision history comments to the new system will never be considered important, if even possible).
Keep important things in the code. That's my experience.
rcs -> sccs -> cvs -> svn -> git, with a trip through MPW Projector. Half the commit comments lately are "why the hell did git do this to me".
At least you got to skip going through such wonders as Source Safe, ClearCase, MKS Source Integrity or Serena Version Manager.
I'm not sure what MPW Projector is, but the rest are pretty mainstream.
It's amazing how many proprietary revision control systems there are, and how much worse they are than the free ones.
RCS clearly wasn't good enough for a team (distributed or not) or concurrent development, but CVS was good enough, with incremental improvements by SVN & Git.
The proprietary systems usually offer integration with a but tracker (mandatory ticket ID on check-in/commit) to lure the ignorant who don't know about commit triggers. Otherwise, they tend to be very slow, frequently time-out their licenses / login-sessions, and/or have a very deficient command line interface making it difficult to script a build system.
I'm not sure what MPW Projector is, but the rest are pretty mainstream.
It's amazing how many proprietary revision control systems there are, and how much worse they are than the free ones.
RCS clearly wasn't good enough for a team (distributed or not) or concurrent development, but CVS was good enough, with incremental improvements by SVN & Git.
The proprietary systems usually offer integration with a but tracker (mandatory ticket ID on check-in/commit) to lure the ignorant who don't know about commit triggers. Otherwise, they tend to be very slow, frequently time-out their licenses / login-sessions, and/or have a very deficient command line interface making it difficult to script a build system.
It sounds like "this.get(0).clientLeft" should have been a single-line function named something like triggerLayoutInMozillaAndFirefoxToFixAnimateForNewDomElement, or if you don't like massive function names, a comment that says that.
Spelunking through commit history shouldn't be necessary learn the intentions behind those kinds of actions.
Spelunking through commit history shouldn't be necessary learn the intentions behind those kinds of actions.
It doesn't matter if it should have been commented or not. The reality is it wasn't. If you get in the habit of explaining your changes in git messages, every line change will have documentation, or at least an owner so you can ask them about it.
If you do need to go git spelunking to figure out what's going on, you'd have to be insane to not add a comment afterwards.
Either way, "shoulda coulda woulda". If the code doesn't have a comment, it doesn't have a comment. These things happen, and you can't change the past. But with git, you can relive it.
If you do need to go git spelunking to figure out what's going on, you'd have to be insane to not add a comment afterwards.
Either way, "shoulda coulda woulda". If the code doesn't have a comment, it doesn't have a comment. These things happen, and you can't change the past. But with git, you can relive it.
Reality could also have been: the commit message wasn't as helpful. Or the message would have been but the file was moved, copied, the indentation level changed, or any number of things that destroys the connection to the original comment. The article sounds like it advocated treating the commit message as the primary means of documentation - which is hardly a good practice. Meaningful identifiers/function names, and comments for non-obvious code should come first. If someone prioritizes elaborate commit messages and a clean history before good code, the techniques outlined in the article might be useful, for sure. But it says: "A project’s history is its most valuable documentation." - which is, frankly, not true for most projects. And if it is true, it's a bug, not a feature.
I did not interpret the article as being git should be a primary source of documentation at all. I have a hard time seeing which part of the article implies that. I think he's just pointing out how it's another tool you can use.
From the article:
A project’s history is its most valuable documentation. (...) The quality of this documentation, however, relies heavily on the diligence of the people involved while writing commit messages.
Requiring such diligence when writing commit messages, while at the same time allowing the same people to write opaque code as shown in the example, would be absurd.
A project’s history is its most valuable documentation. (...) The quality of this documentation, however, relies heavily on the diligence of the people involved while writing commit messages.
Requiring such diligence when writing commit messages, while at the same time allowing the same people to write opaque code as shown in the example, would be absurd.
According to your logic, the author of this code should write a detailed explanation in the commit message, except he probably won't. Shame isn't it?
This would only seem to work for relatively fine grained commits or projects in maintenance mode.
Apart from that, to rigorously apply it would break the author's own advice or common sense source control practise - suppose I make 4 changes in separate files to fix a bug. Do I check them in separately so that I can put my pseudo code comments into the revision history? Now I have broken the atomicity of my revision history. If I check them in all together do I type a whole essay into the revision history about why each change was made in each file? It'll quickly all fall apart.
It also relies on the reader recognizing that they need to be curious about the code here. What it if didn't look so curious? It could easily get cleaned up or modified without a comment to alert the reader.
For people and projects in specific contexts it can work but there are plenty of situations where this is a terrible idea.
Apart from that, to rigorously apply it would break the author's own advice or common sense source control practise - suppose I make 4 changes in separate files to fix a bug. Do I check them in separately so that I can put my pseudo code comments into the revision history? Now I have broken the atomicity of my revision history. If I check them in all together do I type a whole essay into the revision history about why each change was made in each file? It'll quickly all fall apart.
It also relies on the reader recognizing that they need to be curious about the code here. What it if didn't look so curious? It could easily get cleaned up or modified without a comment to alert the reader.
For people and projects in specific contexts it can work but there are plenty of situations where this is a terrible idea.
Totally agree with the "might me good for maintenance mode" sentiment. I'm working on a pre-1.0 project. I'm thinking about the few commits where I was first implementing localStorage caching. Tons of files were effected on each commit. If there was a particularly tricky line in there (there were several), how would I have specified it in a commit? That'd be extremely hard to read when compared to the alternative of putting the comment above the code.
Honestly, I think your example is a better demonstration of this than the article's. You make a change in four places, make a single commit, and then someone reading the code later can use the VCS to find all of the relevant parts of the code that deal with any particular line they're looking at.
I agree with the author that historical information about how a codebase has evolved is important. I would also argue that code comments are not always the best place for this historical information (if you don’t know about the deep past of a bit of code, then why would you want to see a code comment describing some change to it?).
I suggest we take a step back and ask if modern version control is the best way to store historical information. Modern version control systems (git, mercurial, etc.) were built within the last decade or so but they were built with the same constraints as the original version control systems of the 1980’s. They are optimized to be disk efficient (and don’t get me started about their command line interfaces). This is crazy!
We should store much more about the programming process than the data gathered if and when a developer chooses to commit. We should record it all- every keystroke. No human generated source of data is ever going to fill up our hard drives or the cloud. Don’t optimize for the disk!
This data can be used to replay programming sessions so that others can learn exactly how the code evolved. Developers could then comment on the evolution of their code. Think of this as a modern commit message. I am working on a project that attempts to do this:
http://www.storytellersoftware.com
I suggest we take a step back and ask if modern version control is the best way to store historical information. Modern version control systems (git, mercurial, etc.) were built within the last decade or so but they were built with the same constraints as the original version control systems of the 1980’s. They are optimized to be disk efficient (and don’t get me started about their command line interfaces). This is crazy!
We should store much more about the programming process than the data gathered if and when a developer chooses to commit. We should record it all- every keystroke. No human generated source of data is ever going to fill up our hard drives or the cloud. Don’t optimize for the disk!
This data can be used to replay programming sessions so that others can learn exactly how the code evolved. Developers could then comment on the evolution of their code. Think of this as a modern commit message. I am working on a project that attempts to do this:
http://www.storytellersoftware.com
I don't see it as optimizing for disk, I see it as optimizing for time, by presenting relevant events vis-à-vis showing every irrelevant detail. Much like a movie or novel doesn't usually show its characters going to the bathroom, neither should my coworkers have to sift through my misspellings, dumb decisions and irrelevant debugging.
I agree that we could benefit from saving more (e.g. relevant exploratory sessions, though those tend to happen in the REPL, not in the code editor), but I disagree with an indiscriminate approach.
I agree that we could benefit from saving more (e.g. relevant exploratory sessions, though those tend to happen in the REPL, not in the code editor), but I disagree with an indiscriminate approach.
Storyteller has ways to filter out your misspellings, dumb decisions, and irrelevant debugging.
While the process for filtering out dumb decisions and irrelevant debugging is a little convoluted at present, filtering out misspellings is really easy if they're made within X seconds (where X is defined by you). Because Storyteller currently only supports IDEs (specifically Eclipse, hopefully with support for Visual Studio soon) you should be able to notice those quickly.
As for processing out dumb decisions, you don't really know they're dumb until after you've made them, and someone new to a part of the project might also have the same idea you had when made those decisions, and seeing that you made them, hopefully coupled with some comments on what went wrong with those choices could push them in a different direction, or help them fill in a piece you were missing. Watching those past decisions could also help you in the future when you come back to some code and can't remember what you did before or why.
Exploratory sessions only happen in REPLs when the language has a REPL. Considering that Storyteller's written in Java, has support only for an IDE that was initially built for Java, and has been written by a bunch of college students and one professor at a college where most CS courses use C++ or Java, REPLs aren't really things most of us use (I want to change that, but there's only so much you can do through an extracurricular organization).
Plus, we're developers. Why store only some data when you can store ALL THE DATA!
While the process for filtering out dumb decisions and irrelevant debugging is a little convoluted at present, filtering out misspellings is really easy if they're made within X seconds (where X is defined by you). Because Storyteller currently only supports IDEs (specifically Eclipse, hopefully with support for Visual Studio soon) you should be able to notice those quickly.
As for processing out dumb decisions, you don't really know they're dumb until after you've made them, and someone new to a part of the project might also have the same idea you had when made those decisions, and seeing that you made them, hopefully coupled with some comments on what went wrong with those choices could push them in a different direction, or help them fill in a piece you were missing. Watching those past decisions could also help you in the future when you come back to some code and can't remember what you did before or why.
Exploratory sessions only happen in REPLs when the language has a REPL. Considering that Storyteller's written in Java, has support only for an IDE that was initially built for Java, and has been written by a bunch of college students and one professor at a college where most CS courses use C++ or Java, REPLs aren't really things most of us use (I want to change that, but there's only so much you can do through an extracurricular organization).
Plus, we're developers. Why store only some data when you can store ALL THE DATA!
Imagine if the author of the novel had to write those irrelevant scenes anyway in order to get to the good stuff. There might be someone, a literature academic for example, who would want to study that material. It wouldn't be for everyone but there are some who might want access to it. My point is that we are generating this history anyway, so why throw it out? There may be someone who wants to see how the code has evolved. Plus, nobody says you have to watch stuff that is not interesting. There are ways to filter out things you aren't interested in.
Most interesting. I recently did some work on a new, version-control-inspired layout for programs, but from a different angle than you suggest: http://akkartik.name/post/wart-layers. I'd love to chat more about the details of what you're trying (email in profile).
Two questions:
1. How is that different than functionizing things? And, is it better? Especially because in wart it looks like your snippets can only be used once.
2. Does this bring you any advantages that well commented code doesn't? From my admittedly limited point of view (I haven't run it, just looked at your two examples) it looks like following the flow of control is a little more difficult, because it looks like your snippets are, when compiled, just placed where their comments are. Because variables are accessible and manipulable in your snippets there isn't any containment like you get with functions.
Again, this is from me only looking at your two examples.
1. How is that different than functionizing things? And, is it better? Especially because in wart it looks like your snippets can only be used once.
2. Does this bring you any advantages that well commented code doesn't? From my admittedly limited point of view (I haven't run it, just looked at your two examples) it looks like following the flow of control is a little more difficult, because it looks like your snippets are, when compiled, just placed where their comments are. Because variables are accessible and manipulable in your snippets there isn't any containment like you get with functions.
Again, this is from me only looking at your two examples.
The biggest limitation of functions is precisely what you point out: they create scopes. So you end up complecting (http://www.infoq.com/presentations/Simple-Made-Easy) what variables you need access to at a time with what variables you want to describe and explain at a time.
I don't think it's controversial that functions have limitations. For example, OO in many ways was an attempt to work around the limitations of functions. But what OO discovered, I think, was that any sort of modularity mechanism when baked into the language brings in its own constraints, which limit the situations where it can be used. The classic example is all the constraints on C prototypes that make any sort of refactoring of include files an NP-hard problem, dooming lots of codebases to never get the reorganization they need to free them from historical baggage. So I've gradually, grudgingly started to focus on more language-independent, tool-based approaches that can overlay an 'untyped' layer atop even the most rigid language.
"Because variables are accessible and manipulable in your snippets there isn't any containment like you get with functions."
My claim (http://akkartik.name/post/readable-bad) is that in seeking local properties like containment/encapsulation we deemphasize global understanding. Both are useful, certainly, but they're often in tension and our contemporary rhetoric ignores the tension. The pendulum has swung so much in favor of local rules for 'good style' that it's worth temporarily undoing some of that work to see what we're giving up, what the benefits of playing fast and loose with local structure might be.
"..following the flow of control is a little more difficult.."
Yeah that's a valid concern. I think literate programming failed to catch on partly because we need at times to see the entire flow of control in a function. Like when we're debugging. I have a vague vision that programmers of the future will work with the expository and 'tangled' views of a program side by side. (In addition to perhaps a view of the runtime execution of a single unit test: http://akkartik.name/post/tracing-tests.)
Your point about reusing snippets is also a good one. That's the benefit of naming fragments in literate programming, isn't it? I hadn't considered that; the examples I've seen never mention it. But emacs org-mode and http://leoeditor.com certainly seem to find reuse useful. Hmm. I haven't encountered the need for reusing snippets so far. That might change, and we can probably come up with some syntax to support it if so. I suspect, however, that our languages already have plenty of primitives for enabling reuse. We don't need any extra tool or meta-linguistic support.
---
Clicking through to your profile I ended up at http://essays.kuntz.co/you-re-probably-not-for-hackers, which suggests we have kindred sensibilities about these questions! (Compare http://akkartik.name/about)
I don't think it's controversial that functions have limitations. For example, OO in many ways was an attempt to work around the limitations of functions. But what OO discovered, I think, was that any sort of modularity mechanism when baked into the language brings in its own constraints, which limit the situations where it can be used. The classic example is all the constraints on C prototypes that make any sort of refactoring of include files an NP-hard problem, dooming lots of codebases to never get the reorganization they need to free them from historical baggage. So I've gradually, grudgingly started to focus on more language-independent, tool-based approaches that can overlay an 'untyped' layer atop even the most rigid language.
"Because variables are accessible and manipulable in your snippets there isn't any containment like you get with functions."
My claim (http://akkartik.name/post/readable-bad) is that in seeking local properties like containment/encapsulation we deemphasize global understanding. Both are useful, certainly, but they're often in tension and our contemporary rhetoric ignores the tension. The pendulum has swung so much in favor of local rules for 'good style' that it's worth temporarily undoing some of that work to see what we're giving up, what the benefits of playing fast and loose with local structure might be.
"..following the flow of control is a little more difficult.."
Yeah that's a valid concern. I think literate programming failed to catch on partly because we need at times to see the entire flow of control in a function. Like when we're debugging. I have a vague vision that programmers of the future will work with the expository and 'tangled' views of a program side by side. (In addition to perhaps a view of the runtime execution of a single unit test: http://akkartik.name/post/tracing-tests.)
Your point about reusing snippets is also a good one. That's the benefit of naming fragments in literate programming, isn't it? I hadn't considered that; the examples I've seen never mention it. But emacs org-mode and http://leoeditor.com certainly seem to find reuse useful. Hmm. I haven't encountered the need for reusing snippets so far. That might change, and we can probably come up with some syntax to support it if so. I suspect, however, that our languages already have plenty of primitives for enabling reuse. We don't need any extra tool or meta-linguistic support.
---
Clicking through to your profile I ended up at http://essays.kuntz.co/you-re-probably-not-for-hackers, which suggests we have kindred sensibilities about these questions! (Compare http://akkartik.name/about)
I think the emphasis on containment and local understanding is good, especially considering that programs are getting huge (which is a separate problem, and what I think really needs to get fixed). With huge programs it's infeasible to fully comprehend the whole program, which means the only thing you can really do is hope that other programmers' functions work as advertised, and focus on perfecting your local domain.
The easiest way to alleviate this, in my opinion, is to focus on building smaller programs which focus on doing one thing well, and combining those together to create larger applications, with preferably a minimum of glue code. In my mind this leads to even more containment as each domain is now accessible only through the specified API.
This could lead to similar problems that you have with the deemphasis of global understanding, because it's still compartmentalizing things, and at each higher level the programmer is just trusting that the lower levels have implemented what they said they would, just like in a huge, single program.
The idea of being T-shaped specifically when it comes to the overall knowledge of the projects you work on seems to be the best way to work on those applications: have a general understanding of the whole project, and a really good understanding of your specific domain (and perhaps an intermediate understanding of those around yours).
The easiest way to alleviate this, in my opinion, is to focus on building smaller programs which focus on doing one thing well, and combining those together to create larger applications, with preferably a minimum of glue code. In my mind this leads to even more containment as each domain is now accessible only through the specified API.
This could lead to similar problems that you have with the deemphasis of global understanding, because it's still compartmentalizing things, and at each higher level the programmer is just trusting that the lower levels have implemented what they said they would, just like in a huge, single program.
The idea of being T-shaped specifically when it comes to the overall knowledge of the projects you work on seems to be the best way to work on those applications: have a general understanding of the whole project, and a really good understanding of your specific domain (and perhaps an intermediate understanding of those around yours).
If I have to later see every dumb thing I let within ten feet of my IDE window while working, I'm going to set the computer on fire and code pen on paper for later transcription.
Ha ha... yes, it sounds painful but imagine you come across a function that you don't fully understand. You can highlight it and watch how that code evolved. The code will be animated very easily (compared to trying to reconstruct the history from some VCS). Most people will never watch (or care about) you writing code but sometimes it may be very useful.
> var>
, two = "bar"
, three = "baz"
While I agree with making code editable in single lines as much as possible, I think this is a particularly bad example. I do prefer the comma first style for arrays and objects, but not for variable declarations. I used to use this exact style a couple years ago, but now I prefer to explicitly declare every variable with `var` to prevent any possible, syntactically correct, error that would result in a global variable.
It's even easier to create three separate var statements and let a JavaScript compressor handle it:
var
var two = "bar";
var three = "baz";It's a good example of a place where a comment should have been added. The user got lucky because the line's last commit happens to contain the meaningful explanation. He could also have stumbled along a formatting change, variable name change, file rename. The spelunking becomes harder than just reading the comment that could have been on top of that line.
Checking the history is much slower than a comment right there in the code. Repeat this a thousand times and you've lost precious time hunting for information.
Great article! Mislav definitely knows his git.
What he didn't point out though is that he was actually the one that contributed that code in the first place.
https://github.com/madrobby/zepto/pull/586
https://github.com/madrobby/zepto/commit/3d92f20966aa02dee82...
As others have commented, long explanations like this have no place in commit messages. Comments should always be used to explain what you're doing and why you're doing it. Commit messages should simply summarize what you did.
A better commit message would have simply been:
fix animate() for elements just added to DOM
See included comments for explanation.
What he didn't point out though is that he was actually the one that contributed that code in the first place.
https://github.com/madrobby/zepto/pull/586
https://github.com/madrobby/zepto/commit/3d92f20966aa02dee82...
As others have commented, long explanations like this have no place in commit messages. Comments should always be used to explain what you're doing and why you're doing it. Commit messages should simply summarize what you did.
A better commit message would have simply been:
fix animate() for elements just added to DOM
See included comments for explanation.
Here's me doing the HN thing and analyzing the code sample rather than the article itself. Sorry in advance.
But if you're going to do this trick and you use a code compiler of any sort, you'll need to assign the value of that clientLeft somewhere. Otherwise your compiler will notice it not doing anything and helpfully optimize it away. So your users in production will see your layout bug and you'll never be able to reproduce it in development.
JavaScript is awesome.
As to the article itself, I'd prefer to see a comment on a line as wacky as this one. It's one well-intentioned lop away from vanishing from that git blame entirely, and then six hours of debugging and research away from finding its way back into place.
Trying to sift through file history to understand what's going on is hard enough on code I wrote myself only a year ago. I wouldn't want to rely on it as the only way of digging into a large shared code base. Yikes.
But if you're going to do this trick and you use a code compiler of any sort, you'll need to assign the value of that clientLeft somewhere. Otherwise your compiler will notice it not doing anything and helpfully optimize it away. So your users in production will see your layout bug and you'll never be able to reproduce it in development.
JavaScript is awesome.
As to the article itself, I'd prefer to see a comment on a line as wacky as this one. It's one well-intentioned lop away from vanishing from that git blame entirely, and then six hours of debugging and research away from finding its way back into place.
Trying to sift through file history to understand what's going on is hard enough on code I wrote myself only a year ago. I wouldn't want to rely on it as the only way of digging into a large shared code base. Yikes.
> But if you're going to do this trick and you use a code compiler of any sort, you'll need to assign the value of that clientLeft somewhere. Otherwise your compiler will notice it not doing anything and helpfully optimize it away. So your users in production will see your layout bug and you'll never be able to reproduce it in development.
This optimization is only possible if the compiler is able to deduce this as a useless function call. In order to do that, the compiler has to deduce (i) that the result is not used, and (ii) that the function has no side effects. (ii) can be very, very hard to deduce.
This optimization is only possible if the compiler is able to deduce this as a useless function call. In order to do that, the compiler has to deduce (i) that the result is not used, and (ii) that the function has no side effects. (ii) can be very, very hard to deduce.
I don't disagree. But I post this because it actually happened to me. Googles closure compiler to be specific. The only way to make it happy was to actually assign the value to the window scope, where it couldn't know whether the value was ever used.
You live in a world of wonder and magic.
If someone puts that code (without comments) probably, the same person won't give such a detailed commit message.
Good luck in wonderland.
It would be useful to make commit comments on code as you make changes that can be used by SCMs and IDEs. See the history of a method change by change complete with the relevant comments. And from an SCM, click on a comment and select from a list of code changes.
And you avoid having to write your comments when you commit. You'd do it in the code when you are more focused on the change.
Even better would be detecting when you are changing code and prompting for the comment or let you select from recent comments.
Then on the SCM side when you commit, each comment could be handled as a separate commit.
Any IDEs already doing some or all?
And you avoid having to write your comments when you commit. You'd do it in the code when you are more focused on the change.
Even better would be detecting when you are changing code and prompting for the comment or let you select from recent comments.
Then on the SCM side when you commit, each comment could be handled as a separate commit.
Any IDEs already doing some or all?
[deleted]
This is exactly why I'm such a bastard when it comes to git history. A clean history isn't something that just gets filed and disappears forever. Unfortunately, lots of people think it's ok to use a message like "fixed stuff". Don't even try that in my codebase though.
My favorite: "making tests pass", while it was very clear that completely new functionality was added - drives me up a wall!
Or totally empty commit messages.
Mostly a good article. I would put more emphasis on using history/annotate ("blame") for timeline and summary information, and using the inline comments for detail information.
Others have mentioned the "no comments" culture. To them I say: each file/class and each function/method/subroutine should have a summary comment, so I can know to skip over the irrelevant modules when I am looking for how to do something. I don't want 80 to 100 character identifiers (getMatrixResultButNotCornerCaseANorCornerCaseB or some such ridiculous name), but I do want a bit more summary than the name, contained within a statement of purpose comment.
Others have mentioned the "no comments" culture. To them I say: each file/class and each function/method/subroutine should have a summary comment, so I can know to skip over the irrelevant modules when I am looking for how to do something. I don't want 80 to 100 character identifiers (getMatrixResultButNotCornerCaseANorCornerCaseB or some such ridiculous name), but I do want a bit more summary than the name, contained within a statement of purpose comment.
When I'm evaluating a project on GitHub, one of the first things I do is walk through the commit history. The info in there is invaluable IMO for getting up to speed on a codebase fast.
Sometimes it happens that code is moved between repositories in a way that doesn't preserve each single commit.
DVCSs are designed to overcome this problem, and there are bridges between various DVCSs, but sadly this still happens.
So, while mastering '<yourvcs> blame' is certainly useful, you shouldn't rely too much on it, and write readable and well documented code.
DVCSs are designed to overcome this problem, and there are bridges between various DVCSs, but sadly this still happens.
So, while mastering '<yourvcs> blame' is certainly useful, you shouldn't rely too much on it, and write readable and well documented code.
For fun I just created a Sublime Text 2 plugin that lets you bring up the git blame->show for selected line(s) of code with a simple shortcut (cmd+shift+m on Mac, alt+shift+m on Linux/Windows): https://github.com/cbumgard/GitCommitMsg
Every line of code is always documented (if it's in a VCS and the commit message is good)
Interesting concept.
Coincidentally, I wrote a gem recently that serves the same function as the git-overwritten script at the end:
https://github.com/ilyakava/stefon
gem install stefon
gem install stefon
Extending code review to commit messages is a big help.
If I can't understand from the commit message, what the change is trying to achieve, I won't even look at the code. Instead I'll ask to clarify the commit message first.
If I can't understand from the commit message, what the change is trying to achieve, I won't even look at the code. Instead I'll ask to clarify the commit message first.
I wish my current coworkers wrote any comment in there commit message...
Perforce time lapse view is similarly amazing.
good work. not enough people who use source control really seem to know what its for...
whilst i'm a big fan of making code good enough to read - and learning to read code properly - its easier to not have to do both
whilst i'm a big fan of making code good enough to read - and learning to read code properly - its easier to not have to do both
Is this Javascript? Why is there no semicolon?
Despite advice to the contrary, Javascript is a line oriented language and you only need the semicolon if you intend to stack a second statement on the same line (kind of like colons in BASIC)
Yeah, I know that's blasphemy, but it's also true: Javascript works just fine WITHOUT all the extra semicolons. The semicolons are only needed in the minds of those who have been misled to believe that they are. One should learn what JS thinks are complete statements -- where to wrap longer statements without causing an error -- as Javascript WILL end statements without semicolons. Better to just never use semicolons in the first place.
And this is all off-topic...
Yeah, I know that's blasphemy, but it's also true: Javascript works just fine WITHOUT all the extra semicolons. The semicolons are only needed in the minds of those who have been misled to believe that they are. One should learn what JS thinks are complete statements -- where to wrap longer statements without causing an error -- as Javascript WILL end statements without semicolons. Better to just never use semicolons in the first place.
And this is all off-topic...
Code like this is extremely brittle with or without that git history, don't rely on it like a crutch as it makes the code obscure, and updating a line somewhere may leave other similar lines updated or not. If you wanted to update the triggerLayout function, you would have to go through the git commit log for every .clientLeft line to see if that one was or wasn't used for triggering layout...