Print

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

[Mephisto]

The Wikipedia page hasn't been updated in a while. According to their architecture page,

OpenKM implements a [buzzwords removed; tldr: web interface] that supports Firefox, Internet Explorer, Safari, Chromium and Google Chrome and the latest versions of Opera.

Even mobile Chrome performed pretty decently.

[Parsely]

So, I tutor entry-level programming students, a lot of whom are experiencing coding for the very first time. I'm typically not shy about criticizing students' formatting because new students have a tendency not to indent and don't write their code consistently or use any comments. The last thing I want to do is tell people there is one correct way to format code, which is why I emphasize consistency and advise using comments to help you plan and understand your own code.

But when I'm reviewing someone's code I have this awful habit of messing with their formatting! I like whitespace a lot so while I'm reading a blob of code I tend to drop in line breaks and put spaces between the operands.

My students like writing like:

Code: [Select]

for(int i=((4/bun)+3*apple*85);i<x;i++;){do.this;}and I hate it. It must be so fucking annoying to some of the students but I just can't stop myself from making it look the way I want it to.

Somebody stop me.

[Mephisto]

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.

[wierd]

Helpful advice?

Remind your students that they need to write code that meets two VERY important conditions.

1) You have to be able to put this code down, and come back to it after a whole year of doing other things, be able to read it, understand what it is doing, and then make reasonable changes.

2) You have to be able to make code that SOMEBODY ELSE can pick up, be able to read it, understand what it is doing, and then make reasonable changes.


Abuse of the ++ operator (especially after a long order-of-operations chain, where a misplaced paren can break things horribly!), and clever math tricks as one-liners, especially ones that do not comment what is being done, are not doing themselves any favors.

Remind them that such condensation *DOES NOT* make their code execute any faster; (EG, it is *NOT* "cleaner", "More efficient", or "More compact".) The compiler will interpret the expression, and produce optimized code. (EG, i=(i+1) and i++ are the same thing. Exactly the same thing. "faster to write" is not a valid use case. The goal should be "Effective communication to your peers". The resulting bytecode will be identical for both cases. One is easy to read. The other is not.)  All it does is make their code look obtuse to a different programmer. 

Yes, I know that will make them cry bitter tears and make all kinds of noise.  Nearly all jobs doing programming work will be as parts of a team.  They need to write code that a team can work with, not just themselves.  That is the purpose of inline documentation, and why you should not do operand-fu with your syntax.   Unless of course, you are TRYING to hide malicious behavior in plain sight, in which case, more power to them.

[Telgin]

Yes, please hammer code formatting into their heads as soon as you can.  Good variable names too.  I loathe trying to read badly formatted code.  I still don't fully understand how someone can take a source file that's formatted properly, dump in a few blocks of text that don't line up, and not feel uneasy.

For more direct suggestions, if you're grading these assignments, one way I've seen someone handle it is to mark off points for bad formatting with the caveat that students can fix the formatting and get the points back, with no limit.  It's a lot of extra work on you, potentially, but seems like an okay system to me.  One possible problem with doing this is that you may want to avoid imposing your own personal style on people at the threat of negative numbers on their paper, so you have to strike a balance between marking points off for not putting braces where you like them and for writing garbled messes like the example you provided.

[Reelya]

To be honest you'd be doing them a big favor by enforcing proper use of braces even if it's enforcing your own preference.

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

Also, getting a line of code that runs isn't good enough. You should be enforcing that they create proper named variables outside the for loop and such and such, because that's what proper professional code that's easy to maintain looks like. The principle of single-responsibility is a good one here: each line of code should have a single responsibility that's clearly indicated through variable names and/or comments.

[Telgin]

To be clear, I meant that these two examples should probably both be considered equally correct:

Code: [Select]

if (something) {
printf("Something.\n");
} else {
printf("Something else.\n");
}


Code: [Select]

if (something)
{
printf("Something.\n");
}
else
{
printf("Something else.\n");
}

Just as long as they're consistent about it.  I rapidly migrated to the former version from the latter after I started writing code professionally, but the latter isn't really wrong.

That said, I probably would insist on students putting braces in conditional blocks, even where they're not mandatory.  I have personally seen bugs arise from not doing that.  Same thing with semicolons in JavaScript.  You don't need them everywhere, but funny things happen sometimes if you leave them out, so please don't.

[McTraveller]

And for the love of all, make sure you communicate that "good comments" are comments that say why the code is there, not what the code is doing.  The code tells you what it is doing.

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.

Edit: wrong word!

[Reelya]

Yep, that one is important. Comments should indicate intent, what the code is meant to do.

One thing you can do is make the student write the program first as only comments, e.g. start as pseudocode then the pseudocode gets left in as comments. This can help get the needed steps and logic straight because it's in English, and it forces them to break the thing up to fit the comments.

[Telgin]

I had to break my own bad habits of adding a comment on every other line saying things like "add them together" when it was plainly obvious I was doing that.

Regarding comments, I'm sitting here right now and reading some code I wrote myself, and I have no idea why I did it.  A comment explaining why I discarded the incoming phone number for this text message system and replaced it with a random number from our database would have been extremely helpful!  Worse, the code appears to work, so I don't know what's going to happen if I try to "fix" it.

[Kagus]

Yep, that one is important. Comments should indicate intent, what the code is meant to do.

Code: [Select]

// this fixes the problem from earlier

[Reelya]

Code: [Select]

//this line is commenting this section of code

[milo christiansen]

Code: [Select]

// They said I needed more comments.


[bloop_bleep]

Code: [Select]

// My
// boss
// said
// I
// have
// to
// write
// more
// lines
// of
// code
// or
// I’ll
// get
// fired


[wierd]

Code: [Select]

*/ Look, I know it is inappropriate to make a comment like this, but for the love of god people, learn how to make a proper multi-line comment.
As for what this is here for; I deleted some 50 lines of comments about bob's new girlfriend being a whore, and bob's replies to Tim about how
he is a dickhead. I am leaving this comment to remind everyone that QA reads these.  Please, be more professional in your conduct, and leave
the nonprofessional behavior for off the clock.  Thanks, and have a wonderful day. --Mark /* 


*/ Does this make you happy, Mark?  God save us all if somebody hits this with sed, and drops an asterisk in the wrong place.
Also, surely you have noticed that this is WHORE.h; Where ELSE do you expect me to make declarations about Bob's girlfriend? --Tim /*

*/ Tim, I am only going to say this once, and once only.  This is not appropriate. The library is the Window Hover Optimization Runtime
Environment. It has nothing to do with "whores".  Please get this to stay in your mind from now on. I really dont want to have to alert HR. --Mark /*

*/ Indeed. Tim, have you considered the most appropriate location for such a declaration might be the side of the men's bathroom stall? --QA6/*

//Great idea! --Tim

*/Bob asserts that the prior implementation of FooBar() results in too much SQUEE, so I have added this gruesome hack to that named function.
Hopefully it fixes the issue with too much SQUEE.  TODO: Make sure that the caller of FooBar() properly types both the input and output of the
function.  Remember, it is uint32, then a string.  Part of Bob's bug report indicates that he was trying to pass uint64 to this function, for gods
know what reason. --Mark /*

*/ OK--- Whoever scrawled a new primitive for FooBar64() on the bathroom wall in red sharpie, with the text
"Markie dont lose this number, you won't have to call nobody else!", when I find you, you will understand why I won 1st place at
the underhanded c competition last year. --Mark /*