Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Keep your source code SIMPLE

medium.com

Post reply on HN
Print view View original

41–50 of 77 posts

Re: Keep your source code SIMPLE

#41

Post by pytester »

tln wrote: post #32
pytester wrote: post #28

Earlier quoted context omitted.

Comments are often a code smell indicating that the code was written in a hard to understand way. On a top notch code base - the kind that almost nobody works on - they probably should be sparse and mostly unnecessary. Moreover, when a lot of people are asked to comment they write stuff like "this function does x to y" when the function is named "x_to_y". No shit sherlock comments I call them. I'd always prefer to ha…

Check out the CPython code base sometime, as an example of a top notch code base. Are the comments sparse?

Depends on the area of the code you look at, but they can be fairly sparse, yes:

https://github.com/python/cpython/blob/master/PC/python_uwp....

I'd say that redis is probably a better example of gold standard clean C code, though, and they follow the rule of "don't comment unless it's decidedly non-obvious" pretty assiduously:

https://github.com/antirez/redis/blob/unstable/src/ae_epoll....

Re: Keep your source code SIMPLE

#42

Post by pytester »

macintux wrote: post #36
pytester wrote: post #28

Earlier quoted context omitted.

Comments are often a code smell indicating that the code was written in a hard to understand way. On a top notch code base - the kind that almost nobody works on - they probably should be sparse and mostly unnecessary. Moreover, when a lot of people are asked to comment they write stuff like "this function does x to y" when the function is named "x_to_y". No shit sherlock comments I call them. I'd always prefer to ha…

Comments are critical for explaining the code that isn't there. I'm skeptical about "sparse".

I'm not sure what you mean. Comments are for explaining code that IS there.

Re: Keep your source code SIMPLE

#43

Post by evil-olive »

tchaffee wrote: post #13
lostgame wrote: post #5

Earlier quoted context omitted.

Sure! The beginnings of functions, for instance, are great places to comment, perhaps even including a definition of some of the subroutines within it. In the case of an exceptionally large subroutine, commenting within the subroutine may be advantageous - but at that point you may consider another function to replace that larger chunk. Variable names that are perhaps obscure and are not practical to rename for whate…

You didn't really answer my question though. I didn't ask where you should comment. I asked for an objective definition of what over-commenting would be.

> I asked for an objective definition of what over-commenting would be.

I don't think what you're asking for is possible. It's an inherently subjective standard.

If an objective definition were possible, then it'd be possible to write a static analysis tool that reads both your code and the comments and flags "over-commenting on line 23, under-commenting on line 457". That could be done with sufficiently advanced AI, but at that point it would just be the subjective opinion of the tool's author being enforced.

Re: Keep your source code SIMPLE

#44

Post by orenkt »

can author of that medium post show real world example of an app, build with those principles and rules from start to end?

it would be also very educational to see decision and design process of an app build with those rules.

Re: Keep your source code SIMPLE

#45

Post by tempguy9999 »

tobr wrote: post #15
taberiand wrote: post #8

My feeling is these paradigms, SOLID and SIMPLE, boil down to basically: small objects, connected minimally, though interfaces. SIMPLE appears to be leaning even more towards the functional programming side of things; I think we should probably just get it over with and accept that composition of functions operating on immutable data structures is just the right way to go.

Is there a language that leans heavily towards immutable data, but steers clear of the, shall we say, dorkier side of functional programming?

What is 'dorky' WRT functional programming?

Re: Keep your source code SIMPLE

#46

Post by replyguy912 »

pytester wrote: post #42
macintux wrote: post #36

Earlier quoted context omitted.

Comments are critical for explaining the code that isn't there. I'm skeptical about "sparse".

I'm not sure what you mean. Comments are for explaining code that IS there.

comments shouldn't explain code period; they are to clarify intent.

Re: Keep your source code SIMPLE

#47

Post by tempguy9999 »

taberiand wrote: post #8

My feeling is these paradigms, SOLID and SIMPLE, boil down to basically: small objects, connected minimally, though interfaces. SIMPLE appears to be leaning even more towards the functional programming side of things; I think we should probably just get it over with and accept that composition of functions operating on immutable data structures is just the right way to go.

> ... composition of functions operating on immutable data structures is just the right way to go

Yeah. No. Maybe. The cost of immutability can be high. Immutability can be very elegant when it's right, but mutability can be clearer other times. As another respondent said, there's no silver bullet. There's no 'right way to go'; as ever it depends.

Re: Keep your source code SIMPLE

#48

Post by adamkl »

BoorishBears wrote: post #34
ISO-morphism wrote: post #21

Earlier quoted context omitted.

This is Clojure. It's functional, but more as a side effect of focusing intently on simple, immutable, persistent data structures and their compositions. I'd strongly recommend looking into it, along with many of the presentations by its initial author Rich Hickey.

Imo no Lisp variant can claim to not be in the "dorkier" side of things ("dorkier" being read as "hard to approach" in my eyes). I'd say Kotlin over Clojure.

I’d suggest you watch Rich’s talk “Simple made easy”. [1]

It’s one of his main points that something like a language being “hard to approach” can be overcome by spending a little effort to learn it (as opposed to sticking with something like Kotlin just because its easy to pick up because it’s familiar). The benefits of learning the unfamiliar (in his case, he’s speaking specifically about Clojure) being that it allows you to write code that is much simpler to reason about.

I have no particular beef with Kotlin (or most any languages... right tool for the job and all), but I have lately become infatuated with Clojure and many of Rich’s viewpoints.

[1] https://www.infoq.com/presentations/Simple-Made-Easy/

Re: Keep your source code SIMPLE

#49

Post by tln »

pytester wrote: post #41
tln wrote: post #32

Earlier quoted context omitted.

Check out the CPython code base sometime, as an example of a top notch code base. Are the comments sparse?

Depends on the area of the code you look at, but they can be fairly sparse, yes: https://github.com/python/cpython/blob/master/PC/python_uwp.... I'd say that redis is probably a better example of gold standard clean C code, though, and they follow the rule of "don't comment unless it's decidedly non-obvious" pretty assiduously: https://github.com/antirez/redis/blob/unstable/src/ae_epoll....

Those two files do have a low ratio of comments. However a large number of files in those code bases have quite a lot more comments... I personally don't think these two code bases have sparse comments, overall, although perhaps it's subjective or my bias is affecting my judgement :)

Eg, to me this is well-commented and I wouldn't call it sparse.

https://github.com/antirez/redis/blob/unstable/src/latency.c

Re: Keep your source code SIMPLE

#50

Post by macintux »

pytester wrote: post #42
macintux wrote: post #36

Earlier quoted context omitted.

Comments are critical for explaining the code that isn't there. I'm skeptical about "sparse".

I'm not sure what you mean. Comments are for explaining code that IS there.

"This looks like a good case for a binary tree but it doesn't scale well under load."

"We would add support for this motherboard that looks a lot like the one we do support, but it doesn't offer feature X."

"We want to add more detailed logs here but we haven't figured out how to cope with the performance hit."

Closely related, comments are also useful for explaining why code that looks wrong/poorly optimized/obsolete isn't actually, which is something that the code itself can't explain.

Post reply on HN