8 ms·
Every line of code is always documented
- TempleOSV2 13y agoTalk to my lawyer. sing absetively_posilutely my_bad check_this_out enough_said pwned You_know hey_Mikey_he_likes_it high_mucky_muck small_talk yada_yada_yada I_veto_that let_me_count_the_ways homo you_better_not bank driving piety but_of_course ho_ho_ho smurfs you_know_a_better_God it_figures charity I_have_an_idea hooah come_and_get_me game_over California on_occassion wrath You_get_what_you_pray_for ------ Your house is on fire and your kids are burning. You are at the store recounting your change, cause you think you got ripped-off.
- shaggyfrog 13y agoIt 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.
- etler 13y agoIt 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.
- jkrems 13y agoReality 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.
- etler 13y agoI 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.
- jpatte 13y agoFrom 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.
- jpatte 13y agoAccording 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?
- gizmogwai 13y agoI wish my current coworkers wrote any comment in there commit message...
- darryl42 13y agoI wish management allowed comments. Commits are work item number and title or work item only. Comments in code are actively removed.
- Roboprog 13y agoFascinating: they care enough to consider such things, but they have made an insane decision. Good luck there.
- Sunlis 13y ago"Updated javascript"
- meistro 13y ago> var one = "foo" , two = "bar" , three = "baz" Agree with the author that this is easier to change, and in JS it will keep you from accidentally leaving a trailing comma. That being said, I find it to be very unreadable(which is where most your time will be spent) and most text editors/IDE's make it a burden to work with.
- sonnym 13y agoWhile 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.
- ryanpetrich 13y agoIt's even easier to create three separate var statements and let a JavaScript compressor handle it: var one = "foo"; var two = "bar"; var three = "baz";
- etler 13y agoThis 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.
- tomhallett 13y agoMy favorite: "making tests pass", while it was very clear that completely new functionality was added - drives me up a wall!
- Zitrax 13y agoOr totally empty commit messages.
- RyanZAG 13y agoYou really shouldn't have to be relying on history for all of that context. It should definitely have been a function simply called 'triggerLayout()'. Then the exact and best method for triggering layout could be put in that function and used throughout the project where necessary, and easily updated if a better method of triggering layout comes along. 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...
- etler 13y ago"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.
- RyanZAG 13y agoWhat? 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.
- etler 13y agoThe 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.
- zimbatm 13y agoIt'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.
- deleted 13y ago[deleted]
- ghubbard 13y ago"is it safe to change or remove that call in the future?" If you remove the line you should end up with a failing test.
- laureny 13y agoGood luck writing a test that makes sure that the CSS animations get properly triggered on select browsers.
- LukeB_UK 13y agoEvery line of code is always documented (if it's in a VCS and the commit message is good)
- ilzmastr 13y agoInteresting 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 https://github.com/ilyakava/stefon gem install stefon
- gtirloni 13y agoChecking 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.
- rymohr 13y agoGreat 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/pull/586 https://github.com/madrobby/zepto/commit/3d92f20966aa02dee8249daaefc5f8b6623e00de 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.
- martincerdeira 13y agoYou 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.
- stretchwithme 13y agoIt 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?
- crazygringo 13y agoBut 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!
- geoka9 13y agoExactly. 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.
- einhverfr 13y agowhat 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.
- hermannj314 13y agoI 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.
- salgernon 13y agorcs -> 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".
- jakejake 13y agoThis 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..?
- geoka9 13y ago> 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.
- ghayes 13y agoAnd 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.
- tetha 13y agoAnd 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".
- mistermann 13y ago> 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.
- forrestthewoods 13y agoPerforce time lapse view is similarly amazing.
- zmmmmm 13y agoThis 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.
- mattdawson 13y agoTotally 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.
- pseut 13y agoHonestly, 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.
- markm208 13y agoI 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 http://www.storytellersoftware.com
- icebraining 13y agoI 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.
- dkuntz2 13y agoStoryteller 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!
- Aga 13y agoExtending 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.
- tshadwell 13y agoIs this Javascript? Why is there no semicolon?
- Roboprog 13y agoDespite 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...
- erichocean 13y agoWhen 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.
- jasonkester 13y agoHere'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.
- tetha 13y ago> 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.
- jasonkester 13y agoI 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.
- jheriko 13y agogood 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
- ithkuil 13y agoSometimes 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.
- Roboprog 13y agoMostly 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.
- chrisbumgardner 13y agoFor 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 https://github.com/cbumgard/GitCommitMsg