Print

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

[MorleyDev]

This is why I say that "code cannot be self-documenting" - code can only tell you what it does, not what it is supposed to be doing.

I'd argue unit and end-to-end tests are a better way of telling you what code is supposed to be doing than comments (though whether you'd call that the code being 'self-documenting' depends on interpretation).

Comments are a fallback for when you don't have tests, but in my experience documentation you can run is far better than documentation that is a fixed point in time. Let's face it, more often than not the comments don't get updated when the supposed to changes.

Also code can indicate the why in it's function names. To take the phone number example, if that was for obfuscation purposes then a function called "obfuscatePhoneNumber" or something like that would tell you the why without needing a comment. And to be honest, I find getting into the habit of breaking things down into lots of small descriptive functions a lot easier than the habit of writing comments.

They're a tool, but I find they're the tool of last resort. Mostly I find I use them when the code is doing something in a particular way to avoid a particular bug/quirk in one of the libraries being used.

(And the above nonsense discussions should take place inside the issue tracker nowadays, obviously ^^)

[wierd]

Oh you're no fun.

[Mephisto]

Comments are a fallback for when you don't have tests, but in my experience documentation you can run is far better than documentation that is a fixed point in time. Let's face it, more often than not the comments don't get updated when the supposed to changes.

So you get a task to work on this section of code you haven't had to deal with. You spend your first hour digging through the test files for something that may or may not exist because your predecessors either didn't write them or shoved the Widget tests into the Frobnitz test directory, oh, and they thought dynamically creating the tests was a great idea so you can't just `find . -name "test_*" | xargs grep "test_widgets_do_the_thing"` even if you manage to figure out what the tests are called.

This seems contrived? Oh hell no, that's my life right now.

[Parsely]

Code: [Select]

for(int i=((4/bun)+3*apple*85);i<x;i++;){do.this;}

This isn't a whitespace issue. This is a general readability issue. If the only takeaway the students get is "this is unreadable, I need to do better", their future coworkers will silently thank you.

I did say I wasn't shy about complaining about their formatting, and I'm not. If I hate reading their code I tell them so, as constructively as possible. But I do remember being frustrated when I was in their position and a mentor would talk about semantics before the logic problem I was struggling with, and I was just musing about that.

However, like Telgin said, you need to make them format the code properly, don't be a suck and format their code for them.

For very new people I prefer to just show them rather than explain it. They all work in Netbeans so the first thing I do when their code looks like crap is I smash that format hotkey, then I fix one function as an example and I interrogate them a little, and I remind them that they're writing the code for an audience, themselves, their teacher, and their future coworkers like wierd said. That's just on the first offense though and only freshmen get that concession, if it shows up later you bet I just say "I'm not reading this, make it look less terrible then call me over again, if you don't know what your code should look like google 'Java syntax'".

But sometimes when I sit down for those I end up just sitting there going "hmmmmm" and unconsciously smashing the keyboard while I think about their actual problem because it's really fun.

I didn't think about it until now but I've been tutoring undergrads for almost 2 years now at this point. I actually had some teenagers asking me questions about "the industry" and stuff because I somehow convinced people I'm salty or something.

[Kagus]

Is that where the name comes from? Because you do things in a manner that is or is related to parsing?

[Parsely]

I'm a species of flowering plant in the family Apiaceae that's widely cultivated as a herb and spice, get it right. I also can't spell, because I'm a vegetable.

[wierd]

You mean that superfluous bitter stuff people put on plates to make them look pretty?  The one other than kale I mean...

[Parsely]

Hey! I'll have you know I'm whatever is the opposite of superfluous and bitter!

[Kagus]

Parsley is just cilantro's less attractive cousin.

[wierd]

Oh?

Tell me, what is it doing in this bowl of pumpkin soup?  Surely, it is not there for flavor!

Spoiler (click to show/hide)

[Mephisto]

I just figured one of us was a fan of text adventure games turned to tabletop RPGs.

[Parsely]

Oh?

Tell me, what is it doing in this bowl of pumpkin soup?  Surely, it is not there for flavor!

Spoiler (click to show/hide)

I guess your family has learned by now not to put any superfluous decorations on your birthday cake.

I just figured one of us was a fan of text adventure games turned to tabletop RPGs.

Oh hey that's a genre I'm not familiar with, looks pretty cool!

[MorleyDev]

This seems contrived? Oh hell no, that's my life right now.

If they're doing that then do you really think the comments they'd write would be any more helpful?

But yeah, teams still ideally need to agree on the standard practices and testing patterns to use. And projects need to be structured in a predictable way inside the project. Or you'll always run into the "what is this even" problem. That's probably the hardest thing to get people to start doing since it's a culture issue not a technical one. And tests don't get you away from that, but I do think they can compliment it.

As for code formatting, well...that's the IDEs job ^^ But seriously, I wonder if it'd help or hurt a students understanding to give them something like Resharper or IntelliJ. I find the code suggestions help standardise the programming style in the language but I'm not sure if people who weren't programming for a few years before being introduced to them would use them as a crutch or not.

[Telgin]

Just an anecdote, but IDE code formatting has only caused more problems than it solved here.  That's mostly because we have tens of thousands of lines of code written in a format that doesn't strictly conform to any automatic formatting tools any of the developers' IDEs here use, so we just kind of don't use them.

As an example, a junior developer came on about 6 months ago, and he learned to write very sloppy JavaScript and then hit a button in his editor to fix it.  Well... said button also replaced tabs with spaces, removed whitespace between function arguments and did all sorts of other things that I had to tell him to unscrew before I let him commit the code.  Apparently there was no way to tell it to use tabs in its automatic formatting, and that just wasn't going to fly since we have so very much code already that uses tabs.

I'm sure there's some way we automatically reformat all of the code in our repos, but I really don't want to do that since it would effectively destroy the commit history.

But on a new project, or one where the team has been disciplined about using automatic and consistent formatting?  Sure, I agree.  Legacy code sucks.

[Parsely]

Just an anecdote, but IDE code formatting has only caused more problems than it solved here.

-snip-

But on a new project, or one where the team has been disciplined about using automatic and consistent formatting?  Sure, I agree.  Legacy code sucks.

That sucks. It's a great tool for teaching students what their code SHOULD look like, but for the reasons you mentioned that's why you never rely on it and you should just automatically be writing consistent, documented code.

As for code formatting, well...that's the IDEs job ^^ But seriously, I wonder if it'd help or hurt a students understanding to give them something like Resharper or IntelliJ. I find the code suggestions help standardise the programming style in the language but I'm not sure if people who weren't programming for a few years before being introduced to them would use them as a crutch or not.

Maybe! I really like IntelliJ, and it is a crutch, but the point of a crutch is to help you walk until you're ready to run. You can't learn to code unless you write code and anything that helps you write code that works is going to make learning easier and more fun.

---

The problem with using IntelliJ, or any new technology for that matter
The teachers, especially in community college, are often old and don't always have the same need to learn new technologies as developers do, which is why some of mine make an effort to bring in their former students who have much more recent and relevant experience, and the deans try to have a population of young adjuncts. A teacher also has to be really really good at using any software they assign so they can help students who might be using it for the first time. At any rate, a teacher has a lot of things to weigh and consider when adding extra tech to their curriculum beyond just the extra workload for themselves and students.

For the people I work with, this is often their very first experience with programming, period. So students already have a lot to get to grips with when it comes to syntax and a bucketload of other new terminology. The IDE is glossed over almost completely in favor of focusing on how to understand conditionals, loops, and data structures (arrays are up there when it comes to the things people struggle with the most and it's the number one reason I have to go to a white board and start drawing). We teach them the barest of the bare minimum about the IDE and they still forget the important stuff, like how to set breakpoints and use the debugger, which the debugger is probably the NUMBER ONE thing I find myself explaining to students.

The other thing is that deploying a technology is a challenge. There are sometimes compatibility or performance issues with the hardware on campus machines. You also have to consider that anything you give access to in labs also might not be accessible from off-campus for homework, which means you need to teach people how to install it at home and/or get it on the remote access tool, which if the school is providing remote access has it's whole own bureaucratic and technical requirements for what can and can't be provided remotely. If students can only write code in lab time it puts a serious constraint on how you structure your course and what you can assign.

All of these costs in effort, time, and maybe money have to be outweighed by the benefit. Is it really worth it to introduce this software for Java I students? Having been in a course where the teacher was only familiar with writing code in a text editor and running his code in the console, fuck yeah it is. (The code for his assignments has been reused for ages and he uses deprecated functions. By far the worst teacher I've ever had but for reasons other than just his minimalist programming techniques.)