Print

Please login or register.
1 Hour 1 Day 1 Week 1 Month Forever
Login with username, password and session length

[Putnam]

y=2; //sets y to 2
x=3; //Sets x to 3
x+=y; //Sets x to equal x+y, which here is 5

[Dutchling]

I was checking some of my code, actually found this:

Code: [Select]

def getName(self): # get the name;_;

[Siquo]

PHP: Method comments as per phpdoc standards, but very few inline comments, unless the structure is off/different, or when I'm talking to API's and it's not clear what it is I am doing and why:

Code: [Select]

// ok here we need to finish the request with an extra linebreak or the deamon will crash
// when we receive the magic code 402 the request was successful. Any other code or null means it failed, so we throw the corresponding exception
I did not make those two up, btw, those are real comments.

Oh and I also do comments like these:

Code: [Select]

// This is so bad I don't even. DAMN YOU <insert ex-coworker name here>!!! DAMN YOU TO HELL!!!

[Telgin]

Oh, I like making rage comments.  I try to keep it civil and not over do it, but I stumbled across this today while maintaining some of my old code:

Code: [Select]

/* This is really stupid, but I can't figure out any way to get Select2 to store the selected
record without a kludge akin to performing dental surgery with a circular saw.  So, do it the
roundabout and stupid way by looking up the service_address entry based on the return value. */

/* lots of code that does AJAX calls to get said value that was retrieved several times earlier but couldn't easily be cached */

In all seriousness though, I try to comment things that are either more complex than you can digest by just looking at the code quickly, or things that are deceptive or otherwise unclear.  Example:

Code: [Select]

// The dates provided are not sanitized at all because the Date form component
// doesn't support inline forms

/* lots of code involving JavaScript date objects and manually setting months, days and years */

With the libraries we use, that would normally be a red flag.  99.99% of the time you can just do something like form_field.get_value() to get a MySQL friendly datetime string, but in that case we couldn't.  There is a mixture of old and new code throughout the system, so cases of removing seemingly unnecessary code in favor of newer approaches crop up.  Someone else stumbling along might be tempted to just wipe the code and replace it with a get_value() call, not realizing the problem.  The comment points out that the standard form components don't work here and that we have to do it the hard way.

That's actually not a great example.  I'm now aware that good examples of what to comment are surprisingly hard to think of.

I just convinced one of my coworkers that we should use Selenium for testing on a feature I'm working on (more like "We should use Selenium. Objections?" "Go right ahead!").

I didn't know what I was missing. There's nothing quite like writing out what I want to happen and then having my browser open up and automagically do stuff.

I actually did something similar here about a month ago using Selenium.  I coded up a test for a device registration system we use at our managed properties, which worked quite well.  My manager was pretty happy with it too.

Then... we never set it up to actually be used.  Then I switched computers and the code was lost in a disk wipe.   

[ECrownofFire]

I like the idea that code explains what you're doing, comments explain WHY you're doing it.

Realistically most of my comments are documentation. Very useful when I come back to some dark corner of my code and I'm wondering what the fuck I was thinking.

[dreadmullet]

I like annotating my code, even when it's not needed. If I have a large function (like 50 or more lines), I split it up by comments telling what each part does. If I come back to it some time later, I can easily read through the function, and it only takes me 5 seconds to figure out what it does, instead of 60 seconds. I think some people would argue that a big function should be split up into many different functions, so the function names act as comments, but I don't like that approach. It just makes things messy. It would replace each easy to read comment with a bunch of function declarations and definitions, and the function names' lengths would get ridiculous.

[Telgin]

I agree about breaking functions up just to keep them shorter.  Instead I generally apply the "rule of 3" (not to be confused with the C++ rule of the same name): once you've used a piece of code in two places, instead of doing it a third time it's time to make it a function.

[MorleyDev]

I tend to find if a function is bigger than 5 lines it's usually too big, takes more than 2 arguments it does too much, and if you have to go into any function it calls to figure out what that function does the naming of that function is poor. I'm of the opinion that functions should do one thing, and they should do it well.

I find comments for me are a failure, a failure of expressiveness of the code. Sure, we all fail sometimes, we all can't quite think of a good name for a function or class (which to me suggests I don't know what the class's responsibility is). But why do we fall, Master Bruce?

The main issue is comments aren't as easy to maintain as actual code, so they gradually become lying liars who lie. And the only thing worse than a redundant comment is an untrue comment.

[Mephisto]

The previous post should have a giant YMMV disclaimer.

Five lines is nothing. One of the smaller views in our Django app is 42 lines excluding comments and blank lines. Yeah, not particularly long, but some are much larger (on the order of 150+ lines). It takes its input (one or two args), messes with the orm, does at least one manipulation on the objects retrieved unless those objects are special cases, and returns the result.

Sure we could split it into several methods, but that's busywork worse than ensuring 100% code coverage. It might feel good, but it doesn't necessarily improve anything on its own. I'm much more into the "methods should be at most one screen height" guideline, but even that must be broken sometimes.

I've also had experience with large amounts of uncommented, poorly-written code (there was a post of mine earlier about 695 lines of uncommented VBScript with one-character variable names). I tend to err on the side of more comments than necessary.

[Siquo]

Yeah, what Mephisto said. Had to work with a guy two jobs ago who refactored everything like that (5 line rule), creating more and more verbose and useless methods.

_{To be fair, it was Java, so verbose and useless was the norm in that company.}

[MorleyDev]

Well of course it's mostly opinion. What works, works after all. Having code that follows SOLID principles is what I desire, I just find that more than 5 lines or more than 2 arguments is often one of the warning signs the Single-Responsibility Principle is being broken. Not always, but often.

Also for me it does depend partly on the toolage. Professionally my work has been mostly in C# with access to Resharper and heavy unit testing (as in the only code without coverage was legacy code not touched in years, and we always added coverage if we needed to touch it). Small functions are easier to test and understand, making them less prone to errors, and resharper makes refactoring functions out and extracting classes into dependencies incredibly simple.

Languages without such excellent tools as Resharper or IntelliJ are always more of a pain to work in and follow SOLID with. Although since I still try to do TDD whenever I can, and tests tend to cause you to write smaller and more focused functions and classes I still tend around the smaller functions. Tests often start to look nasty when you start to break Single-Responsibility Principle or put too much behaviour into a single function, which is a good indicator something is going wrong.

[dreadmullet]

I'm trying to understand what use unit tests are for me. If I'm writing a math library, unit tests are obviously pretty critical. But what if I have a function that generates perlin noise? How would unit tests work there?

[MagmaMcFry]

I'm trying to understand what use unit tests are for me. If I'm writing a math library, unit tests are obviously pretty critical. But what if I have a function that generates perlin noise? How would unit tests work there?

I guess you could test that noise is in fact generated, and that it follows certain statistical distributions. The test would obviously not pass every time even if the code works, but the test has no false positives, which is much more important.

[MorleyDev]

Unit tests verify your assumptions are correct and the code behaves as you expect. I'm a serial recompiler, I need to see things work as soon as I write them. Unit tests let me do that. Write test, run test, see test fail. Write code, run test again, see test pass. Refactor where needed, run tests again to prove it still works.

Second, they force you to actually and immediately use the code you're writing, which forces you to think about how it'll be used and what error conditions exist etc. This also means the tests can act as documentation: They show you and other developers how to use the code.

With perlin noise, you know what given seeds will generate so check that the seeds do indeed generate that. Inject the randomness somehow because otherwise tests will occasionally fail. That's bad and flaky tests are very annoying. I have a dislike for randomness in tests outside of monkey testing. A false positive is a bug, a false negative is a regular annoyance and time sink.

If you are ever refactoring/optimising the algorithm and the test breaks, it means you broke the algorithm.

[Virex]

Yeah, what Mephisto said. Had to work with a guy two jobs ago who refactored everything like that (5 line rule), creating more and more verbose and useless methods.

_{To be fair, it was Java, so verbose and useless was the norm in that company.}

Obviously, the number of lines before you scratch your head should depend on the language. Take for example 5 lines of Haskell vs. 5 lines of Java vs. 5 lines of assembler.