41–50 of 71 posts
Someone made an Atom plugin: https://atom.io/packages/squint-test
While the patterns themselves are interesting, the idea that all code must be rearranged in to smaller functions to be “refactored” seems a little juvenile.
Wouldn't this invite consternation during code reviews because it doesn't have anything to do with the current feature? Or are you one of the lucky few who gets to exercise professional judgment when working?
While the patterns themselves are interesting, the idea that all code must be rearranged in to smaller functions to be “refactored” seems a little juvenile.
The code that is easiest to revisit is decomposed into separate functions that are each trivial to understand. They are used to compose similarly trivial functions, and so on. Ideally every point of your program from input to output can be understood clearly and immediately.
While the patterns themselves are interesting, the idea that all code must be rearranged in to smaller functions to be “refactored” seems a little juvenile.
There’s an exercise for creative writing that my lit major friend told me about. You take everything you’ve written and cut it up into sentences. You just push the sentences around until something clicks and you figure out how to write your way out of the “stuckness”. Refactoring has rediscovered this trick, among others.
Earlier quoted context omitted.
The code might be obvious, but if you don't include the reason why it exists it's a target for removal. And having too many of those makes either for garbage or hard decisions when refactoring. Writing the rationale is the most important comment you must not skip. And there would be links to design documentation so that it can be kept up to date. (For non-programmers.)
Why it exists ought to be explained by the existence of a test. This isn't always possible, but it's far more possible than many developers seem to think.
When I read code I care about what the code is supposed to do and why it's supposed to do that.
There is code that passes the current tests and is logically sound but no longer fits the business requirements. Knowing that it was implemented to solve a certain use case helps the reader / reviewer see whether the code and the test still fit or if they should be updated.
The best comments I've come across comment the intention and any context that isn't immediately obvious from the function.
> ... not so good code: if it was, we wouldn’t need a comment... How much longer will this rumor persist that "good code" doesn't need commenting? Good comments explain things that aren't immediately obvious from the code.
Like what? It can’t be the “how” - the code should be able to express that clearly. It can’t be the “what”, again that should be apparent from some combination of code and configuration / metadata. So that leaves the “why”. To my mind, code comments are the worst place to record why a particular implementation exists. The why often needs collaboration with non-coders.
Commenting the purpose of the code and maybe a link to some documentation allows a future reader to see if the code still fulfills the requirements.
Sandi Metz talked about a thing she does in her 2014 All the Little Things talk that she calls the "Squint Test". The idea being that you can tell a lot about the code from only its shape and colours by squinting at it. Someone made an Atom plugin: https://atom.io/packages/squint-test
Earlier quoted context omitted.
Most code should be boring and immediately obvious. I don't run into lots of real world code that needs much explaining. Sometimes you do something weird or not-obvious for good reason, but I see plenty of comments explaining things that only need to be explained due to poor design. Also poor comments that don't really explain anything that isn't obvious by looking.
def clean_start_year(x): # Account for the 7 year offset in the database return x + 7 def process_record(record): record['start year'] = clean_start_year(record['record']) It's perfectly obvious what this code does, but without the comment it's totally unclear why it does what it does.
const database_year_offset = 7;
fix_start_year(year):
return year + database_year_offset;
process_record(record):
record['start year'] = fix_start_year(record['record']);
DougBTX had the same idea, at the same time. I don't think their version needs the comment either. EDIT: Dang you removed a perfectly fine post :)
Earlier quoted context omitted.
Most code should be boring and immediately obvious. I don't run into lots of real world code that needs much explaining. Sometimes you do something weird or not-obvious for good reason, but I see plenty of comments explaining things that only need to be explained due to poor design. Also poor comments that don't really explain anything that isn't obvious by looking.
def clean_start_year(x): # Account for the 7 year offset in the database return x + 7 def process_record(record): record['start year'] = clean_start_year(record['record']) It's perfectly obvious what this code does, but without the comment it's totally unclear why it does what it does.