Every line of code is always documented

#1

Post by jessaustin » Sat, Feb 08, 2014, 7:04 PM UTC

Every line of code is always documented
mislav.uniqpath.com

Re: Every line of code is always documented

#2

Post by TempleOSV2 » Sat, Feb 08, 2014, 7:13 PM UTC

Talk 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.

Re: Every line of code is always documented

#3

Post by shaggyfrog » Sat, Feb 08, 2014, 7:16 PM UTC

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.

Re: Every line of code is always documented

#4

Post by gizmogwai » Sat, Feb 08, 2014, 7:20 PM UTC

I wish my current coworkers wrote any comment in there commit message...

Re: Every line of code is always documented

#5

Post by meistro » Sat, Feb 08, 2014, 7:42 PM UTC

> 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.

Re: Every line of code is always documented

#6

Post by etler » Sat, Feb 08, 2014, 7:45 PM UTC

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.

Re: Every line of code is always documented

#7

Post by tomhallett » Sat, Feb 08, 2014, 7:53 PM UTC

etler wrote: post #6

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!

Re: Every line of code is always documented

#8

Post by etler » Sat, Feb 08, 2014, 8:07 PM UTC

shaggyfrog wrote: post #3

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.

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.

Re: Every line of code is always documented

#9

Post by RyanZAG » Sat, Feb 08, 2014, 8:07 PM UTC

You 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...

Re: Every line of code is always documented

#10

Post by zimbatm » Sat, Feb 08, 2014, 8:08 PM UTC

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.