Is this Javascript? Why is there no semicolon?
Every line of code is always documented
61–70 of 104 posts
Re: Every line of code is always documented
#62You 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 hist…
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).
Re: Every line of code is always documented
#63I 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 sto…
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…
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!
Re: Every line of code is always documented
#64Earlier quoted context omitted.
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: // Hack to trigger layout change in latest Mozilla Then, whoever interested in the hack can read the full explanation from the commit message. Basically, for simple code with unclear purpose, I'd go with short comment in the code…
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 t…
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.
Re: Every line of code is always documented
#65Re: Every line of code is always documented
#66But 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…
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.
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.
Re: Every line of code is always documented
#67You 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 hist…
Way to miss the point completely.
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.
Re: Every line of code is always documented
#68I wish my current coworkers wrote any comment in there commit message...
"Updated javascript"
Re: Every line of code is always documented
#69When 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.
Re: Every line of code is always documented
#70I 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 sto…
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).