{"id":50,"date":"2024-01-18T09:38:14","date_gmt":"2024-01-18T09:38:14","guid":{"rendered":"https:\/\/permutationcity.co.uk\/bp\/?p=50"},"modified":"2024-01-18T09:38:14","modified_gmt":"2024-01-18T09:38:14","slug":"in-one-glance","status":"publish","type":"post","link":"https:\/\/permutationcity.co.uk\/bp\/2024\/01\/18\/in-one-glance\/","title":{"rendered":"In one glance"},"content":{"rendered":"\n

I’m surprised how often I come across large functions in projects. It’s not uncommon to come across functions\nwith hundreds of lines. I’ve searched for something, jump in to the middle of a file, and then scrolled\nup desperately looking for the start of the function so I can start to understand what it’s doing.<\/p>\n\n\n\n

I think it’s a good idea to adopt a maximum size for functions in a project. If one of your functions is\ncreeping up towards that size then it needs to be refactored. Normally that can be done\nwith smaller functions represent sensible parts of the task. Maybe the inner part of a loop is broken out\ninto it’s own function or each case of a switch-statement gets a function call rather than a body.\nOccasionally it might be necessary to have foobar_part1<\/code> to foobar_part3<\/code>. This isn’t ideal.\nWhile a good function name helps it is often still easier to understand a badly named but small function.<\/p>\n\n\n\n

I think the best maximum size for a function is one screen<\/strong>. If you can see the entire function in one\nglance then it is much easier understand and reason about it. If you have to scroll up and down in order to\nsee the whole thing then you must rely on your memory for the bits you can’t see. Critically it’s much easier\nto write a really long function from scratch because you do remember the bits you’ve just written. However it’s\nmuch harder for everyone else<\/em> to then understand that function. This also applies to “future you” who has\nlong forgotten what this function was for.<\/p>\n\n\n\n

Most modern editors allow some sort of code folding<\/a>. By hiding\nsome code branches this lets you fit more on one screen. However this means you can’t see everything in one\nglance. If you fold away code then you are again relying on your memory. Moving code out to a separate\nfunction call is fundamentally different as you can see exactly what information is being passed back\nand forth.<\/p>\n\n\n\n

How large do you mean?<\/h2>\n\n\n\n

When I say the maximum size for a function should be one screen that means it’s not fixed.\nIt depends on what hardware the function is going to be read on. That means if you (and the rest of your\nteam) use ultralite laptops then the maximum size should be smaller. If you all have widescreen monitors\nrotated 90 degrees then the maximum size can be larger. Getting a better monitor really could change how\nyou code. Right now for me on a laptop that means a maximum size of about 70 lines.<\/p>\n\n\n\n

I think some people will find this lack of specificity problematic. I don’t think you can make a set of rules\nthat are going to work everywhere for everyone. If you are the only one who reads your code then look to\nyou own hardware. If you work with a team then consider their hardware as well. If your code is going out for\nmore public consumption then it probably pays to be conservative, maybe, 60 lines.<\/p>\n\n\n\n

Breaking the rule<\/h2>\n\n\n\n

I sometimes write a function which goes above this maximum size. I think it’s okay to do this when the function\nis very easy to understand<\/em> despite the larger size. Typically this means it follows a very regular pattern.\nAn example is an if-else-statement with simple if-expressions and one-line if-bodies. However if the\nif-expressions have a variety of different forms or if there are long if-bodies then try to stick to the\nsize limit.<\/p>\n\n\n\n

Can this be a more general idea?<\/h2>\n\n\n\n

Recently I’ve been wondering if a “maximum size of one screen” rule should be applied more generally. The idea\nis that it’s easier to understand something if you can see the whole thing at once. That could apply to:\nclasses, interfaces, or system architectures. For a class to be easy to use<\/em> then, perhaps, the public\ninterface should be at most one screen. For a class to be easy to understand<\/em> then, perhaps, the whole interface\nshould be at most one screen. For an entire system to be easy to understand then you have to be able to\ndescribe or diagram it on one screen.<\/p>\n\n\n\n

I don’t think the argument for, say, a class is as strong as it is for a function. It can be possible to use\na class while ignoring some of it’s capabilities. However that does leave you open to the class behaving\nunexpected because you were ignoring them. I’ll have to experiment a bit to see if limiting classes sizes\npays off with better code or whether breaking the class apart just ends up with more complexity.<\/p>\n","protected":false},"excerpt":{"rendered":"

I’m surprised how often I come across large functions in projects. It’s not uncommon to come across functions with hundreds of lines. I’ve searched for something, jump in to the middle of a file, and then scrolled up desperately looking for the start of the function so I can start to understand what it’s doing. […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_import_markdown_pro_load_document_selector":0,"_import_markdown_pro_submit_text_textarea":"","footnotes":""},"categories":[1],"tags":[8],"class_list":["post-50","post","type-post","status-publish","format-standard","hentry","category-general","tag-standards"],"_links":{"self":[{"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/posts\/50","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/comments?post=50"}],"version-history":[{"count":1,"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/posts\/50\/revisions"}],"predecessor-version":[{"id":51,"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/posts\/50\/revisions\/51"}],"wp:attachment":[{"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/media?parent=50"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/categories?post=50"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/tags?post=50"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}