[Raynes]

http://makinggoodsof...ting-good-code/

Might be interesting to the OOP folks. Doesn't quite apply to me.

[baavgai]

Nice. I tend to agree with all of it, which is refreshing.

"1.- DRY: Don't repeat yourself." YES! Refactor something, anything. Cut and paste, we love you but you make crap code.

"2.- Write short methods." Yes.

"3.- Use good names for your classes, methods and variables." Applies to all programming, unless the name is "i".

"4.- Assign the right responsibility to each class." "5.- Keep your code organized." Same thing, really only comes with experience. Number 2 relates to this as well.

"6.- Create lots of unit tests." I'd say, write your code so that it's possible to unit test, which is more often the problem.

"7.- Refactor often and sooner." This is an extension of number 1.

"8.- Comments are evil." I am not alone! Someone understands me. Thank you.

"9.- Code to an interface, not to an implementation." This is kind of the point of OO and is really part of 4 and 5.

"10.- Have code reviews." Only really works if the ALL the reviewers are competent. Otherwise, this can be an exercise in herding cats. Rather, frequent iterative project reviews with the people who will have to use your work is probably more helpful.

Upon review, "Keep your code organized" is the point of more than half of these, which I also agree with.

[Martyr2]

Great commandments as usual. Most are picked up as you program. I still have a problem with the whole "comments are evil" thing despite the original author clarifying their position.

The author makes the point that great code which is readable should not need comments. Generally this is true for comments that are to describe how things are being done. But as many programmers know, sometimes it is crucial to have comments that not only mention how something is done but WHY it is being done.

Sure you write a function that is maybe 5 lines long and very readable. It shows you exploding a line into pieces and parsing it. Fine, readers of the code get that because it is very clean and simple. I still expect a comment there saying why that function exists in the system to begin with. Nothing elaborate of course, just enough to explain to new programmers what that function is being used for. Perhaps something like "// This parses a line for the edit post screen of the CMS".

This practice is great in that it also helps make maintenance easier. Lets say we eliminate part of the system that edits posts. We know, based on the comment, that this code is tied to that subsystem and generally safe to get rid of.

Another great practice is to use comments to describe assumptions for using the function. I have known code shops to use comments to label which of input is expected, expected output or any limitations of the function. Coders don't have time to read your 30 lines (or even 10 lines) over and over again to remind themselves what the function is doing. Read a comment line in a quick visual scan and be on your way.

Comments in general are not evil, we just have evil people using them in evil ways. I happen to think they are necessary and I would expect at least a line describing each and every function.

If you are ever in doubt on the scope or need of a comment, ask a friend to read your comment and recite back to you what the expectations or need for the function is. If they can do that, the comment is serving its purpose.

[baavgai]

Martyr2, on 6 Jun, 2009 - 09:25 AM, said:

I would expect at least a line describing each and every function.

This would drive me mental. It is also usually completely unnecessary, if you stick to commandment three.

// return the current user.
public IUser GetCurrentUser() { //...

I mean, really?

// This parses a line for the edit post screen of the CMS". 
public ParseResults GetParseResults(string line) { //...

Methods don't exist in a vacuum. They belong to objects or namespaces that further define their function. They also reveal their function by the other parts of the program that rely on them.

If you see a comment in my production code, it really means something. It's not part of the comment white noise, it a glaring exclamation mark that says "this code is unusual, it's some something non intuitive or unexpected, pay attention before you mess with it."

It's also a style thing, of course, but I find comments more than just superfluous. They are detrimental to the smooth flow of the language syntax, and therefore provide the opposite of their intended purpose, which is clarity.

[Raynes]

I like how you can document Clojure functions. It's idiomatic to do this:

(defn afunc 
  "Prints it's argument to the screen."
   [x] (println x))

Afterwards, once you load it into the REPL, you could type (doc afunc) and it would print its documentation. Metadata rocks.

This post has been edited by Raynes: 06 June 2009 - 10:13 AM

[Dantheman]

Is it just me, or does it feel like the only reason Raynes chose to learn Clojure is to feel "special" and making sure that everybody knows that? No offense of course.

This post has been edited by Dantheman: 06 June 2009 - 03:03 PM

[girasquid]

Python's got a pretty similar way to embed metadata onto your functions - you can just do this to add some documentation:

def myfunc(foo):
	"""
	This is my function. It does the things - or it gets the virus again.
	"""
	print foo

And then afterwards, you can just use myfunc.__doc__ to retrieve the docstring.

It's a pretty useful way to write comments - but I tend to write comments that explain the thought process that went into the function, along with explaining what some of the arguments are supposed to be instead of writing about what the function does or why it exists.

[Raynes]

Dantheman, on 6 Jun, 2009 - 02:00 PM, said:

Is it just me, or does it feel like the only reason Raynes chose to learn Clojure is to feel "special" and making sure that everybody knows that? No offense of course.

Is it just me, or do every time I even /mention/ Clojure in passing, I get insulted by somebody? I was mentioning a feature related to code documentation, because they were talking about it. I'm also learning Haskell, I know a small bit about Scala, and on my list in the future is F#, Java, C, Python, and many many others.

Yeah, I just want to be special.

@girasquid Cool! I didn't know you could do that in Python. I'll probably make heavy use of that when I learn Python.

This post has been edited by Raynes: 06 June 2009 - 03:46 PM

[cfoley]

Java has something similar too. It generates stuff like this.

/**
* Adds a and b together.
*/
int sum(int a, int b ) {
  return a + b;
  }

I used to do this religiously for every method. Now I just make sure my method names are meaningful. If I were to write an API for use by other programmers I'd include javadoc comments for that.

This post has been edited by cfoley: 06 June 2009 - 04:09 PM

[baavgai]

Raynes, on 6 Jun, 2009 - 04:37 PM, said:

I'll probably make heavy use of that when I learn Python.

I actually thought of Python when you showed the Clojure syntax.

For the record, C# has the most exhaustive version of this type of mechanism I've seen.

///<summary>
/// Returns pixel with a specified coordinates.
///</summary>
///<param name="x">Non-negative x-coordinate of pixel.</param>
///<param name="y">Non-negative y-coordinate of pixel.</param>
///<returns></returns>
public object GetPixel(int x, int y)

I'm sure there are extension parsers that can beat this, but it's the best I've seen out of the box. The skeleton of this can be generated by built in mechanism and also by some clever plugins. The documentation generator can create document similar to what Microsoft offers on their website.

[AdamSpeight2008]

That style also gives you the Intellisense text descriptions, and all of them are exported as a XML file.

This post has been edited by AdamSpeight2008: 06 June 2009 - 06:20 PM

[KYA]

Comments are not really for me, they are for others who work with or might read my code.

And, since I work mainly with school stuff now, whatever the instructor wants comment wise, I'll put them in there, even if I don't think it needs it.

[c0mrade]

I'm with Martyr2 on the comments thing... Comments should explain why the instructions for the computer are what they are from a business perspective - this is something that should never be described in code. Of course, depending on what type of programming you do you might not have much business logic thus not so many comments. Also, comments are critical in a language like C where many ugly hacks are taken to improve performance. Once again, this is commenting on the why not the what.

Quote

Might be interesting to the OOP folks. Doesn't quite apply to me.

Really? What's the logic behind that? You like fp so universal principals of programming and completely irrelevant to you?

Quote

I like how you can document Clojure functions. It's idiomatic to do this:

Yes, Python introduced most of us to that feature. How is it any better than a comment? Why would you ever want your program to read a comment clearly intended only for human use?

Quote

Is it just me, or do every time I even /mention/ Clojure in passing, I get insulted by somebody?

I think the thing that pisses people off is you come across as seeming to think you are the only one who knows anything about fp, and that you are special for being different. You mentioned the doc feature of Clojure - but why? Nobody was talking about the different ways languages incorporate comments, they were talking about the comments themselves.

Not trying to dig at you man, just trying (probably unsuccessfully) to help.

This post has been edited by c0mrade: 06 June 2009 - 07:38 PM

[Raynes]

Quote

Quote

Might be interesting to the OOP folks. Doesn't quite apply to me.

Really? What's the logic behind that? You like fp so universal principals of programming and completely irrelevant to you?

Actually, most of it does apply to FP. However, he targets OOP specifically in case you didn't notice, what he wrote about classes and such doesn't apply to me because /as of right now, I don't use any Object Oriented programming languages/. It could of course be modified a bit and still apply, but I think you simply misunderstood me.

Quote

Quote

I like how you can document Clojure functions. It's idiomatic to do this:

Yes, Python introduced most of us to that feature. How is it any better than a comment? Why would you ever want your program to read a comment clearly intended only for human use?

I was only saying that it's a neat feature to have. I'm happy I mentioned it, because I didn't know about how many other forms it comes in in other languages. As for the second question, the Clojure core is documented with comments and metadata documentation. Instead of having to go look up a function in Clojure.core, all you have to do is fire up a (probably already running) REPL and (doc "func") or to search for a function (find-doc "func"). That is a useful feature, and it's the main reason I mentioned it.

Quote

Quote

Is it just me, or do every time I even /mention/ Clojure in passing, I get insulted by somebody?

I think the thing that pisses people off is you come across as seeming to think you are the only one who knows anything about fp, and that you are special for being different. You mentioned the doc feature of Clojure - but why? Nobody was talking about the different ways languages incorporate comments, they were talking about the comments themselves.

Not trying to dig at you man, just trying (probably unsuccessfully) to help.

I don't see how I come across like that. I mentioned the doc feature because people were talking about commenting. Would we be having this conversation has I mentioned the doc feature in Python? I don't think we would. I mention a simple feature in a language and now I'm getting run through shit for it. I don't get that. I spend most of my time in the Clojure and Haskell community, which are surprisingly big. I'm not sure how I could possibly feel special or think I'm the only one who knows anything about FP. My observations are that, ever since KYA targeted me, I've become a target for a free remark everytime I even mention Clojure.

The only reason I mentioned the doc feature is because I thought it was pretty neat. Sorry for trying to participate in the community everyone.

[KYA]

Le sigh. I made one comment, that was supposed to be more fun (if I recall, the comment was made in the Lounge, I could be wrong though) then ire.

But there is some substance to the notion that all you ever talk about is FP, which, from my foxhole, is a double edged sword. I haven't made any comments since then and aside from this little digression, I will refrain from doing so.