How To Make Your Codebase More Readable

Abbreviations - High Information Density HID - Low Information Density LID - High Information Volume HIV - Low Information Volume LIV - Those who can handle both well HID/HIV HID and HIV - Those who can handle well but can only handle well HID/LIV HID LIV - Those who can only handle well but can handle well LID/HIV LID HIV / - Those who can only handle and well LID LIV LID LIV TL;DR(The Whole Article Takes About 30 Minutes To Read In Full Depth) Information Density A small piece of information representation referring to a large piece of information content has HID , whereas a large piece of information representation referring to a small piece of information content has LID. Unfortunately, different programmers have different capacities on facing information density. In general, those who can handle very well will prefer very terse codes, as it'll be more effective and efficient to both write and read them that way for such software engineers, while writing and reading verbose codes are just wasting their time in their perspectives; Those who can only handle very well will prefer very verbose codes, as it'll be easier and simpler to both write and read them that way for such software engineers, while writing and reading terse codes are just too complicated and convoluted in their perspectives. HID LID Unfortunately, very effective and efficient software engineers are generally very intolerant towards extreme ineffectiveness or inefficiencies, so all we can do is to try hard. Ideally, we should be able to handle very HID well while still being very tolerant towards LID , so we'd be able to work well with codes having all kinds of information density. Information Volume A code chunk having a large piece of information content that aren't abstracted away from that code chunk has HIV , whereas a code chunk having only a small piece of information content that aren't abstracted away from that code chunk has LIV . Unfortunately, different software engineers have different capacities on facing information volume, so it seems that the best way's to find a happy medium that can break a very long function into fathomable chunks on one hand, while still keeping the function call stack manageable on the other. In general, those who can handle very well will prefer very long functions, as it'll be more effective and efficient to draw the full picture without missing any nontrivial relevant detail that way for such software engineers, while writing and reading very short functions are just going the opposite directions in their perspectives; HIV Those who can only handle very well will prefer very short functions, as it'll be easier and simpler to reason about well-defined abstractions(as long as they don't in nontrivial ways) that way for such software engineers, while writing and reading long functions are just going the opposite directions in their perspectives. LIV leak Unfortunately, very effective and efficient software engineers are generally very intolerant towards extreme ineffectiveness or inefficiencies(especially when those small function abstractions do in nontrivial ways), so all we can do is to try hard. Ideally, we should be able to handle very HIV well while still being very tolerant towards LIV , so we'd be able to work well with codes having all kinds of information volume. leak Combining Information Density With Information Volume While information density and volume are closely related, there's no strict implications from one to the other, meaning that there are different combinations of these 2 factors and the resultant style can be very different from each other. For instance, doesn't imply nor vice versa, as it's possible to write a very terse long function and a very verbose short function; doesn't imply nor vice versa for the very same reasons. In general, the following largely applies to most codebases, even when there are exceptions: HID LIV LID HIV Very HID + HIV = Massive Ball Of Complicated And Convoluted Spaghetti Legacy Very HID + LIV = Otherwise High Quality Codes That Are Hard To Fathom At First Very LID + HIV = Excessively Verbose Codes With Tons Of Redundant Boilerplate Very LID + LIV = Too Many Small Functions With The Call Stacks Being Too Deep Teams With Programmers Having Different Styles The combinations of these conflicts may be: It seems to me that many coding standard/style conflicts can be somehow explained by the conflicts between HID and LID , and those between HIV and LIV , especially when both sides are being more and more extreme. Very HID/HIV + HID/LIV = Too Little Architecture vs Too Weak To Fathom Codes Very HID/HIV + LID/HIV = Being Way Too Complex vs Doing Too Little Things Very HID/HIV + LID/LIV = Over-Optimization Freak vs Over-Engineering Freak Very HID/LIV + LID/HIV = Too Concise/Organized vs Too Messy/Verbose Very HID/LIV + LID/LIV = Too Hard To Read At First vs Too Ineffective/Inefficient Very LID/HIV + LID/LIV = Too Beginner Friendly vs Too Flexible For Impossibles Conclusions Of course, one doesn't have to go for the , , or extremes, as there's quite some middle grounds to play with. HID LID HIV LIV In fact, I think the best of the best software engineers should deal with all these extremes well while still being able to play with the middle grounds well, provided that such an exceptional software engineer can even exist at all. Nevertheless, it's rather common to work with at least some of the software engineers falling into at least 1 extremes, so we should still know how to work well with them. After all, nowadays most of the real life business codebase are about teamwork but not lone wolves. By exploring the importance of information density, information volume and their relationships, I hope that this article can help us think of some aspects behind codebase readability and the nature of conflicts about it, and that we can be more able to deal with more different kinds of codebase and software engineers better. I think that it's more feasible for us to be able to read codebase with different information density and volume than asking others and the codebase to accommodate with our information density/volume limitations. Also, this article actually implies that readability's probably a complicated and convoluted concept, as it's partially objective at large(e.g.: the existence of consistent formatting and meaningful naming) and partially subjective at large(e.g.: the ability to handle different kinds of information density and volume for different software engineers). Maybe many avoidable conflicts involving readability stems from the tendency hat many software engineers treat readability as easy, simple and small concept that are entirely objective. Information Density A Math Analogy Consider the following math formula that are likely learnt in high school(Euler's Formula): Most of those who've studied high school math well should immediately fathom this, but for those who don't, you may want to try to fathom this text equivalent, which is more verbose: The Euler number to the power of (the imaginary unit multiplied by theta in radian) equals cosine theta in radian plus the imaginary unit multiplied by sine theta in radian I hope that those who can't fathom the above formula can at least fathom the above text :) This brings the importance of information density: . For instance, the above formula has whereas the above text has . A small piece of information representation referring to a large piece of information content has HID , whereas a large piece of information representation referring to a small piece of information content has LID HID LID In this example, those who're good at math in general and high school math in particular will likely prefer the formula over the text equivalent as they can probably fathom the former instantly while feeling that the latter's just wasting their time; Those who're bad at math in general and high school math in particular will likely prefer the text equivalent over the formula as they might not even know the fact that cisx is the short form of cosx + isinx. For those who can handle well, even if they don't know what Euler number is at all, they should still be able to deduce these corollaries within minutes if they know what cisx is: HID But for those who can only handle well, they'll unlikely be able to know what's going on at all, even if they know how to use the binomial theorem and the truncation operator. LID Now let's try to fathom this math formula that can be fathomed using just high school math: While it doesn't involve as much math knowledge nor concepts as those in the Euler's Formula, I'd guess that only those who're really, really exceptional in high school math and math in general can fathom this within seconds, let alone instantly, all because of this formula having such a ridiculously . If you can really fathom this instantly, then I'd think that you can really handle very very well, especially when it comes to math :D HID HID So what if we try to explain this by text? I'd come up with the following try: (The summation of m variables from x1 to xm) to the power of n equals the summation of (n elements, each being the combination of selecting r elements from n - 1 elements, where r is the outermost summation counter from 0 to n - 1, multiplied by the summation of (m elements, each being xi to the power of n - r, where i is the middle summation counter from 1 to m, multiplied by (the summation of m variables from x1 to xm except xi) to the power of r)) Maybe you can finally fathom what this formula is, but still probably not what it really means nor how to use it meaningfully, let alone deducing any useful corollary. However, with the text version, at least we can clearly see just how high the information density is in that formula, as even the information density for the text version isn't actually anything low. These 2 math examples aim to show that, HID, as long as being kept in moderation, is generally preferred over the LID counterparts. But once the information density becomes too unnecessarily and unreasonably high, the much more verbose versions seeming to be too verbose is actually preferred in general, especially when their information density isn't low. Some Examples Showing HID vs LID There are programming parallels to the above math analogy: terse and verbose codes. Unfortunately, different programmers have different capacities on facing information density, just like different people have different capacities on fathoming math. For instance, the ternary operator is a very obvious terse example on this(Javascript ES5): x = condition1 ? value1 : condition2 ? value2 : value3; var Whereas a verbose if/else if/else equivalent can be something like this: x; (condition1 === ) { x = value1; } (condition2 === ) { x = value2; } { x = value3; } var if true else if true else Those who're used to read and write terse codes will likely like the ternary operator version as the if/else if/else version will likely be just too verbose for them; Those who're used to read and write verbose codes will likely like the if/else if/else version as the ternary operator version will likely be just too terse for them(I've seen production codes with if (variable === true), so don't think that the if/else if/else version can only be totally made up examples). In this case, I've worked with both styles, and I guess that most programmers can handle both. Similarly, Javascript and some other languages support short circuit evaluation, which is also a terse style. For instance, the || and && operators can be short circuited this way: isValid && (array || []).concat(object || canUseDefault && ); return default Where a verbose equivalent can be something like this(it's probably too verbose anyway): returnedValue; (isValid === ) { returnedArray; isValidArray = (array !== ) && (array !== ); (isValidArray === ) { returnedArray = array; } { returnedArray = []; } pushedObject; isValidObject = (object !== ) && (object !== ); (isValidObject === ) { pushedObject = object; } (canUseDefault === ) { pushedObject = ; } { pushedObject = canUseDefault; } ( .isArray(pushedObject) === ) { returnedArray = returnedArray.concat(pushedObject); } { returnedArray = returnedArray.concat([pushedObject]); } returnedValue = returnedArray; } { returnedValue = isValid; } returnedValue; var if true var var null undefined if true else var var null undefined if true else if true default else if Array true else else return Clearly the terse version has very while the verbose version has very . Those who can handle well will likely fathom the terse version instantly while needing minutes just to fathom what the verbose version's really trying to achieve and why it's not written in the terse version to avoid wasting time to read so much code doing so little meaningful things; Those who can only handle well will likely fathom the verbose version within minutes while probably giving up after trying to fathom the terse version for seconds and wonder what's the point of being concise when it's doing just so many things in just 1 line. In this case, I seriously suspect whether anyone fathoming Javascript will ever write in the verbose version at all, when the terse version is actually one of the popular idiomatic styles. HID LID HID LID Now let's try to fathom this really, really terse codes(I hope you won't face this in real life): ( texts = [], num = min; num <= max; num += increment) { primeMods = primes.map( { num % prime; }); texts.push(primeMods.reduce( { (text + (mod || words[i])).replace(mod, ); }, ) || num); } texts.join(textSeparator); for var var ( ) function prime return ( ) function text, mod, i return "" "" return If you can fathom this within seconds or even instantly, then I'd admit that you can really handle ridiculously exceptionally well. However, adding these lines will make it clear: HID min = , max = , increment = ; primes = [ , ], words = [ , ], textSeparator = ; var 1 100 1 var 3 5 "Fizz" "Buzz" "\n" So all it's trying to do is the very, very popular programming test in a ridiculously terse way. So let's try this much more verbose version of this programming test: Fizz Buzz Fizz Buzz texts = []; ( num = min; num <= max; num = num + increment) { text = ; primeCount = primes.length; ( i = ; i < primeCount; i = i + ) { prime = primes[i]; mod = num % prime; (mod === ) { word = words[i]; text = text + word; } } (text === ) { texts.push(num); } { texts.push(text); } } texts.join(textSeparator); var for var var "" var for var 0 1 var var if 0 var if "" else return Even those who can handle very well should still be able to fathom this verbose version within seconds, so do those who can only handle very well. Also, considering the inherent complexity of this generalized , the verbose version doesn't have much boilerplate, even when compared to the terse version, so I don't think those who can handle very well will complain about the verbose version much. On the other hand, I doubt whether those who can only handle very well can even fathom the terse version, let alone in a reasonable amount of time(like minutes), if I didn't tell that it's just . In this case, I really doubt what's the point of writing in the terse version when I don't see any nontrivial issue in the verbose version(while the terse version's likely harder to fathom). HID LID Fizz Buzz HID LID Fizz Buzz Back To The Math Analogy Imagine that a mathematician and math professor who's used to teach postdoc math now have to teach high school math to elementary math students(I've heard that a very small amount of parents are so ridiculous to want their elementary children to learn high school math even when those children aren't interested in nor good at math). That's almost mission impossible, but all that teacher can do is to first consolidate the elementary math foundation of those students while fostering their interest in math, then gradually progress to middle school math, and finally high school math once those students are good at middle school math. All those students can do is to work extremely hard to catch up such great hurdles. Unfortunately, it seems to me that it'd take far too much resources, especially time, when those who can handle very well try to teach those who can only handle very well to handle . Even when those who can only handle very well can eventually be nurtured to meet the needs imposed by the codebase, it's still unlikely to be worth it, especially for software teams with very tight budgets, no matter how well intentioned it is. HID LID HID LID So should those who can only handle very well train up themselves to be able to handle ? I hope so, but I doubt that it's similar to asking a high school student to fathom postdoc math. While it's possible, I still guess that most of us will think that it's so costly and disproportional just to apply actually basic math formulae that are just written in terse styles; LID HID Should those who can handle very well learn how to deal with well as well? I hope so, but I doubt that's similar to asking mathematicians to abandon their mother tongue when it comes to math(using words instead of symbols to express math). While it's possible, I still guess that most of us will think that it's so excessively ineffective and inefficient just to communicate with those who're very poor at math when discussing about advanced math. HID LID So it seems that maybe those who can handle well and those who can only handle well should avoid working with each other as much as possible. But that'd mean all these: HID LID The current software team must identify whether the majority can handle well or can only handle well, which isn't easy to do and most often totally ignored HID LIV The software engineering job requirement must state that whether being able to deal with well will be prioritized or even required, which is an uncommon statement HID All applicants must know whether they can handle well, which is overlooked HID The candidate screening process must be able to tell who can handle well HID Most importantly, the team must be able to hire enough candidates who can handle well, and it's obvious that many software teams just won't be able to do that HID Therefore, I don't think it's an ideal or even reasonable solution, even though it's possible. Alternatively, those who can handle very well should try their best to only touch the part of the codebase, while those who can only handle very well should try their best to only touch the part of the codebase. But needless to say, that's way easier said than done, especially when the team's large and the codebase can't be really that modular. HID HID LID LID A Considerable Solution With an IDE supporting , one can try something like this: collapsing comments isValid && (array || []).concat(object || canUseDefault && ); /* var returnedValue; if (isValid === true) { var returnedArray; var isValidArray = (array !== null) && (array !== undefined); if (isValidArray === true) { returnedArray = array; } else { returnedArray = []; } var pushedObject; var isValidObject = (object !== null) && (object !== undefined); if (isValidObject === true) { pushedObject = object; } else if (canUseDefault === true) { pushedObject = default; } else { pushedObject = canUseDefault; } if (Array.isArray(pushedObject) === true) { returnedArray = returnedArray.concat(pushedObject); } else { returnedArray = returnedArray.concat([pushedObject]); } returnedValue = returnedArray; } else { returnedValue = isValid; } return returnedValue; */ return default Of course it's not practical when the majority of the codebase's so terse that those who can only handle very well will struggle most of the time, but those who can handle very well can try to do the former some favors when there aren't lots of terse codes for them. LID HID The point of this comment's to be a working compromise between the needs of reading codes effectively and efficiently for those who can handle very HID well, and the needs of fathoming code easily and simply for those who can only handle very LID well. Summary In general, those who can handle very well will prefer very terse codes, as it'll be more effective and efficient to both write and read them that way for such software engineers, while writing and reading verbose codes are just wasting their time in their perspectives; Those who can only handle very well will prefer very verbose codes, as it'll be easier and simpler to both write and read them that way for such software engineers, while writing and reading terse codes are just too complicated and convoluted in their perspectives. HID LID Unfortunately, very effective and efficient software engineers are generally very intolerant towards extreme ineffectiveness or inefficiencies, so all we can do is to try hard. Ideally, we should be able to handle very HID well while still being very tolerant towards LID , so we'd be able to work well with codes having all kinds of information density. Information Volume An Eating Analogy Let's say we're ridiculously big eaters who can eat 1kg of meat per meal. But can we eat all that 1kg of meat in just 1 chunk? Probably not, as our mouth just won't be big enough, so we'll have to cut it into digestible chunks. However, can we eat it if it becomes a 1kg of very fine-grained meat powder? Maybe, but that's likely daunting or even dangerous(extremely high risk of severe choking) for most of us. So it seems that the best way's to find a happy medium that works for us, like cutting it into chunks that are just small enough for our mouth to digest. There might still be many chunks but at least they'll be manageable enough. The same can be largely applied to fathoming codes, even though there are still differences. Let's say you're reading a well-documented function with 100k lines and none of its business logic are duplicated in the entire codebase(so breaking this function won't help code reuse right now). Unless we're so good at fathoming big functions that we can keep all these 100k lines of implementation details in our head as a whole, reading such a function will likely be daunting or even dangerous(extremely high risk of fathom it all wrong) for most of us, assuming that we can indeed fathom it within a feasible amount of time(like within hours). On the other hand, if we break that 100k line function into extremely small functions so that the can be as deep as 100 calls, we'll probably be in really big trouble when we've to debug these functions having bugs that don't have apparently obvious causes nor caught by the current test suite(no test suite can catch all bugs after all). function call stack After all, traversing such a deep without getting lost and having to start all over again is like eating tons of very fine-grained meat powders without ever choking severely. Even if we can eventually fix all those bugs with the test suite updated, it'll still unlikely to be done within a reasonable amount of time(talking about days or even weeks when the time budget is tight). call stack This brings the importance of information volume: For instance, the above 100k line function has whereas the above small functions with deep has . A code chunk having a large piece of information content that aren't abstracted away from that code chunk has HIV , whereas a code chunk having only a small piece of information content that aren't abstracted away from that code chunk has LIV . HIV call stack LIV For instance, if possible, breaking that 100k line function into those in which the largest ones are 1k line functions and the ones with the deepest is 10 calls can be a good enough balance. So it seems that the best way's to find a happy medium that can break that 100k line function into fathomable chunks on one hand, while still keeping the call stack manageable on the other. call stack While fathoming a 1k line function is still hard for most of us, it's at least practical; While debugging functions having with 10 calls is still time-consuming for most of us, it's at least realistic to be done within a tight budget. call stacks A Small Example Showing HIV vs LIV Consider the following small example(Some of my Javascript ES5 codes with comments removed): Unfortunately, different software engineers have different capacities on facing information volume, just like different people have different mouth size. Version(17 methods with the largest being 4 lines and the deepest being 11) - LIV call stack $.result = { (!$gameSystem.satbParam( )) { ._uncachedResult(note, argObj_, ); } ._updatedResult(note, argObj_); }; $._updatedResult = { cache = ._cache.result_(note, argObj_); (_SATB.IS_VALID_RESULT(cache)) cache; ._updatedResultWithCache(note, argObj_); }; $._updatedResultWithCache = { result = ._uncachedResult(note, argObj_, ); ._cache.updateResult(note, argObj_, result); result; }; $._uncachedResult = { ( ._rules.isAssociative(note)) { ._associativeResult(note, argObj_, funcNameSuffix); } ._nonAssociativeResult(note, argObj_, funcNameSuffix); }; $._associativeResult = { partResults = ._partResults(note, argObj_, funcNameSuffix); defaultResult = ._pairs.default(note, argObj_); ._rules.chainedResult( partResults, note, argObj_, defaultResult); }; $._partResults = { priorities = ._rules.priorities(note); funcName = + funcNameSuffix + ; resultFunc = [funcName].bind( , note, argObj_); priorities.map(resultFunc).filter(_SATB.IS_VALID_RESULT); }; $._partResultWithoutCache_ = { ._uncachedPartResult_(note, argObj_, part, ); }; $._partResultWithCache_ = { cache = ._cache.partResult_(note, argObj_, part); (_SATB.IS_VALID_RESULT(cache)) cache; ._updatedPartResultWithCache_(note, argObj_, part); }; $._updatedPartResultWithCache_ = { result = ._uncachedPartResult_(note, argObj_, part, ); ._cache.updatePartResult(note, argObj_, part, result); result; }; $._uncachedPartResult_ = { list = [ + funcNameSuffix](note, part); (list.length <= ) ; ._rules.chainedResult(list, note, argObj_); }; $._nonAssociativeResult = { list = [ + funcNameSuffix](note); defaultResult = ._pairs.default(note, argObj_); ._rules.chainedResult(list, note, argObj_, defaultResult); }; $._pairFuncListWithoutCache = { ._uncachedPairFuncList(note, ); }; $._pairFuncListWithCache = { cache = ._cache.pairFuncList_(note); cache || ._updatedPairFuncListWithCache(note); }; $._updatedPairFuncListWithCache = { list = ._uncachedPairFuncList(note, ); ._cache.updatePairFuncList(note, list); list; }; $._uncachedPairFuncList = { funcName = + funcNameSuffix; ._rules.priorities(note).reduce( { list.concat( [funcName](note, part)); }.bind( ), []); }; $._pairFuncListPartWithCache = { cache = ._cache.pairFuncListPart_(note, part); cache || ._updatedPairFuncListPartWithCache(note, part); }; $._updatedPairFuncListPartWithCache = { list = ._pairFuncListPartWithoutCache(note, part); ._cache.updatePairFuncListPart(note, part, list); list; }; $._pairFuncListPartWithoutCache = { func = ._pairs.pairFuncs.bind( ._pairs, note); ._cache.partListData(part, ._battler).map(func); }; ( ) function note, argObj_ if "_isCached" return this "WithoutCache" return this ( ) function note, argObj_ var this if return return this ( ) function note, argObj_ var this "WithCache" this return ( ) function note, argObj_, funcNameSuffix if this return this return this ( ) function note, argObj_, funcNameSuffix var this var this return this ( ) function note, argObj_, funcNameSuffix var this var "_partResult" "_" var this this return ( ) function note, argObj_, part return this "WithoutCache" ( ) function note, argObj_, part var this if return return this ( ) function note, argObj_, part var this "WithCache" this return ( ) function note, argObj_, part, funcNameSuffix var this "_pairFuncListPart" if 0 return undefined return this ( ) function note, argObj_, funcNameSuffix var this "_pairFuncList" var this return this ( ) function note return this "WithoutCache" ( ) function note var this return this ( ) function note var this "WithCache" this return ( ) function note, funcNameSuffix var "_pairFuncListPart" return this ( ) function list, part return this this ( ) function note, part var this return this ( ) function note, part var this this return ( ) function note, part var this this return this this Version(10 methods with the largest being 12 lines and the deepest being 5) - HIV call stack $.result = { (!$gameSystem.satbParam( )) { ._uncachedResult(note, argObj_, ); } cache = ._cache.result_(note, argObj_); (_SATB.IS_VALID_RESULT(cache)) cache; result = ._uncachedResult(note, argObj_, ); ._cache.updateResult(note, argObj_, result); result; }; $._uncachedResult = { ( ._rules.isAssociative(note)) { priorities = ._rules.priorities(note); funcName = + funcNameSuffix + ; resultFunc = [funcName].bind( , note, argObj_); partResults = priorities.map(resultFunc).filter(_SATB.IS_VALID_RESULT); defaultResult = ._pairs.default(note, argObj_); ._rules.chainedResult( partResults, note, argObj_, defaultResult); } list = [ + funcNameSuffix](note); defaultResult = ._pairs.default(note, argObj_); ._rules.chainedResult(list, note, argObj_, defaultResult); }; $._partResultWithoutCache_ = { ._uncachedPartResult_(note, argObj_, part, ); }; $._partResultWithCache_ = { cache = ._cache.partResult_(note, argObj_, part); (_SATB.IS_VALID_RESULT(cache)) cache; result = ._uncachedPartResult_(note, argObj_, part, ); ._cache.updatePartResult(note, argObj_, part, result); result; }; $._uncachedPartResult_ = { list = [ + funcNameSuffix](note, part); (list.length <= ) ; ._rules.chainedResult(list, note, argObj_); }; $._pairFuncListWithoutCache = { ._uncachedPairFuncList(note, ); }; $._pairFuncListWithCache = { cache = ._cache.pairFuncList_(note); (cache) cache; list = ._uncachedPairFuncList(note, ); ._cache.updatePairFuncList(note, list); list; }; $._uncachedPairFuncList = { funcName = + funcNameSuffix; ._rules.priorities(note).reduce( { list.concat( [funcName](note, part)); }.bind( ), []); }; $._pairFuncListPartWithCache = { cache = ._cache.pairFuncListPart_(note, part); (cache) cache; list = ._pairFuncListPartWithoutCache(note, part); ._cache.updatePairFuncListPart(note, part, list); list; }; $._pairFuncListPartWithoutCache = { func = ._pairs.pairFuncs.bind( ._pairs, note); ._cache.partListData(part, ._battler).map(func); }; ( ) function note, argObj_ if "_isCached" return this "WithoutCache" var this if return // $._updatedResultWithCache START var this "WithCache" this return // $._updatedResultWithCache END ( ) function note, argObj_, funcNameSuffix if this // $._associativeResult START // $._partResults START var this var "_partResult" "_" var this this var // $._partResults END var this return this // $._associativeResult START // $._nonAssociativeResult START var this "_pairFuncList" var this return this // $._nonAssociativeResult END ( ) function note, argObj_, part return this "WithoutCache" ( ) function note, argObj_, part var this if return // $._updatedPartResultWithCache_ START var this "WithCache" this return // $._updatedPartResultWithCache_ END ( ) function note, argObj_, part, funcNameSuffix var this "_pairFuncListPart" if 0 return undefined return this ( ) function note return this "WithoutCache" ( ) function note var this if return // $._updatedPairFuncListWithCache START var this "WithCache" this return // $._updatedPairFuncListWithCache END ( ) function note, funcNameSuffix var "_pairFuncListPart" return this ( ) function list, part return this this ( ) function note, part var this if return // $._updatedPairFuncListPartWithCache START var this this return // $._updatedPairFuncListPartWithCache END ( ) function note, part var this this return this this In case you can't fathom what this example's about, you can read this simple flow chart(It doesn't mention the fact that the actual codes also handle whether the cache will be used): Even though the underlying business logic's easy to fathom, different people will likely react to the and Version differently. Those who can handle very well will likely find the version less readable due to having to unnecessarily traverse all these excessively small methods(the smallest ones being 1 liners) and enduring the highest call stack of 11 calls(from $.result to $._pairFuncListPartWithoutCache); Those who can only handle very well will likely find the version less readable due to having to unnecessarily fathom all these excessively mixed implementation details as a single unit in one go from the biggest method with 12 lines and enduring the presence of 3 different combined just in the biggest and most complex method($._uncachedResult). HIV LIV HIV LIV LIV HIV levels of abstractions Bear in mind that it's just a small example which is easy to fathom and simple to explain, so the differences between the and styles and the potential conflicts between those who can handle very well and those who can only handle very well will only be even larger and harder to resolve when it comes to massive real life production codebases. HIV LIV HIV LIV Back To The Eating Analogy Imagine that the size of the mouth of various people can vary so much that the largest digestible chunk of those with the smallest mouth are as small as a very fine-grained powder in the eyes of those with the largest mouth. Let's say that these 2 extremes are going to eat together sharing the same meal set. How should these meals be prepared? An obvious way's to give them different tools to break these meals into digestible chunks of sizes suiting their needs so they'll respectively use the tools that are appropriate for them, meaning that the meal provider won't try to do these jobs themselves at all. It's possible that those with the smallest mouth will happily break those meals into very fine-grained powders, while those with the largest mouth will just eat each individual food as a whole without much trouble. Unfortunately, it seems to me that there's still no well battle-tested automatic tools that can effectively and efficiently break a large code chunk into well-defined smaller digestible code chunks with configurable size and complexity without nontrivial side effects, so those who can only handle very well will have to do it manually when having to fathom large functions. Also, even when there's such a tool, such automatic work's still effectively refactoring that function, thus probably irritating colleagues who can handle very well. LIV HIV So should those who can only handle very well train up themselves to be able to deal with ? I hope so, but I doubt that's similar to asking those with very small mouths to increase their mouth size. While it's possible, I still guess that most of us will think that it's so costly and disproportional just to eat foods in chunks that are too large for them; Should those who can handle very well learn how to deal with well as well? LIV HIV HIV LIV I hope so, but I doubt that's similar to asking those with very large mouths to force themselves to eat very fine-grained meat powders without ever choking severely(getting lost when traversing a very deep ). While it's possible, I still guess that most of us will think that it's so risky and unreasonable just to eat foods as very fine-grained powders unless they really have no other choices at all(meaning that they should actually avoid these as much as possible). call stack So it seems that maybe those who can handle well and those who can only handle well should avoid working with each other as much as possible. But that'd mean all these: HIV LIV The current software team must identify whether the majority can handle well or can only handle well, which isn't easy to do and most often totally ignored HIV LIV The software engineering job requirement must state that whether being able to deal with well will be prioritized or even required, which is an uncommon statement HIV All applicants must know whether they can handle well, which is overlooked HIV The candidate screening process must be able to tell who can handle well HIV Most importantly, the team must be able to hire enough candidates who can handle well, and it's obvious that many software teams just won't be able to do that HIV Therefore, I don't think it's an ideal or even reasonable solution, even though it's possible. Alternatively, those who can handle very well should try their best to only touch the part of the codebase, while those who can only handle very well should try their best to only touch the part of the codebase. But needless to say, that's way easier said than done, especially when the team's large and the codebase can't be really that modular. HIV HIV LIV LIV An Imagined Solution Let's say there's an IDE which can display the function calls in the inlined form, like from: $.result = { (!$gameSystem.satbParam( )) { ._uncachedResult(note, argObj_, ); } ._updatedResult(note, argObj_); }; $._updatedResult = { cache = ._cache.result_(note, argObj_); (_SATB.IS_VALID_RESULT(cache)) cache; ._updatedResultWithCache(note, argObj_); }; $._updatedResultWithCache = { result = ._uncachedResult(note, argObj_, ); ._cache.updateResult(note, argObj_, result); result; }; $._uncachedResult = { ( ._rules.isAssociative(note)) { ._associativeResult(note, argObj_, funcNameSuffix); } ._nonAssociativeResult(note, argObj_, funcNameSuffix); }; $._associativeResult = { partResults = ._partResults(note, argObj_, funcNameSuffix); defaultResult = ._pairs.default(note, argObj_); ._rules.chainedResult( partResults, note, argObj_, defaultResult); }; $._partResults = { priorities = ._rules.priorities(note); funcName = + funcNameSuffix + ; resultFunc = [funcName].bind( , note, argObj_); priorities.map(resultFunc).filter(_SATB.IS_VALID_RESULT); }; $._partResultWithoutCache_ = { ._uncachedPartResult_(note, argObj_, part, ); }; $._partResultWithCache_ = { cache = ._cache.partResult_(note, argObj_, part); (_SATB.IS_VALID_RESULT(cache)) cache; ._updatedPartResultWithCache_(note, argObj_, part); }; $._updatedPartResultWithCache_ = { result = ._uncachedPartResult_(note, argObj_, part, ); ._cache.updatePartResult(note, argObj_, part, result); result; }; $._uncachedPartResult_ = { list = [ + funcNameSuffix](note, part); (list.length <= ) ; ._rules.chainedResult(list, note, argObj_); }; $._nonAssociativeResult = { list = [ + funcNameSuffix](note); defaultResult = ._pairs.default(note, argObj_); ._rules.chainedResult(list, note, argObj_, defaultResult); }; $._pairFuncListWithoutCache = { ._uncachedPairFuncList(note, ); }; $._pairFuncListWithCache = { cache = ._cache.pairFuncList_(note); cache || ._updatedPairFuncListWithCache(note); }; $._updatedPairFuncListWithCache = { list = ._uncachedPairFuncList(note, ); ._cache.updatePairFuncList(note, list); list; }; $._uncachedPairFuncList = { funcName = + funcNameSuffix; ._rules.priorities(note).reduce( { list.concat( [funcName](note, part)); }.bind( ), []); }; $._pairFuncListPartWithCache = { cache = ._cache.pairFuncListPart_(note, part); cache || ._updatedPairFuncListPartWithCache(note, part); }; $._updatedPairFuncListPartWithCache = { list = ._pairFuncListPartWithoutCache(note, part); ._cache.updatePairFuncListPart(note, part, list); list; }; $._pairFuncListPartWithoutCache = { func = ._pairs.pairFuncs.bind( ._pairs, note); ._cache.partListData(part, ._battler).map(func); }; ( ) function note, argObj_ if "_isCached" return this "WithoutCache" return this ( ) function note, argObj_ var this if return return this ( ) function note, argObj_ var this "WithCache" this return ( ) function note, argObj_, funcNameSuffix if this return this return this ( ) function note, argObj_, funcNameSuffix var this var this return this ( ) function note, argObj_, funcNameSuffix var this var "_partResult" "_" var this this return ( ) function note, argObj_, part return this "WithoutCache" ( ) function note, argObj_, part var this if return return this ( ) function note, argObj_, part var this "WithCache" this return ( ) function note, argObj_, part, funcNameSuffix var this "_pairFuncListPart" if 0 return undefined return this ( ) function note, argObj_, funcNameSuffix var this "_pairFuncList" var this return this ( ) function note return this "WithoutCache" ( ) function note var this return this ( ) function note var this "WithCache" this return ( ) function note, funcNameSuffix var "_pairFuncListPart" return this ( ) function list, part return this this ( ) function note, part var this return this ( ) function note, part var this this return ( ) function note, part var this this return this this To be displayed as something like this: $.result = { (!$gameSystem.satbParam( )) { ( ._rules.isAssociative(note)) { priorities = ._rules.priorities(note); partResults = priorities.map( { func = ._pairs.pairFuncs.bind( ._pairs, note); list = ._cache.partListData( part, ._battler).map(func); (list.length <= ) ; ._rules.chainedResult(list, note, argObj_); }).filter(_SATB.IS_VALID_RESULT); defaultResult = ._pairs.default(note, argObj_); ._rules.chainedResult( partResults, note, argObj_, defaultResult); } priorities = ._rules.priorities(note); list = priorities.reduce( { func = ._pairs.pairFuncs.bind( ._pairs, note); l = ._cache.partListData( part, ._battler).map(func); list.concat(l); }.bind( ), []); defaultResult = ._pairs.default(note, argObj_); ._rules.chainedResult( list, note, argObj_, defaultResult); } cache = ._cache.result_(note, argObj_); (_SATB.IS_VALID_RESULT(cache)) cache; result; ( ._rules.isAssociative(note)) { priorities = ._rules.priorities(note); partResults = priorities.map( { cache = ._cache.partResult_(note, argObj_, part); (_SATB.IS_VALID_RESULT(cache)) cache; c = ._cache.pairFuncListPart_(note, part); list; (c) { list = c; } { func = ._pairs.pairFuncs.bind( ._pairs, note); list = ._cache.partListData( part, ._battler).map(func); ._cache.updatePairFuncListPart(note, part, list); } result = ; (list.length > ) { result = ._rules.chainedResult(list, note, argObj_); } ._cache.updatePartResult(note, argObj_, part, result); result; }).filter(_SATB.IS_VALID_RESULT); defaultResult = ._pairs.default(note, argObj_); result = ._rules.chainedResult( partResults, note, argObj_, defaultResult); } cache = ._cache.pairFuncList_(note), list; (cache) { list = cache; } { priorities = ._rules.priorities(note); list = priorities.reduce( { cache = ._cache.pairFuncListPart_(note, part); l; (cache) { l = cache; } { func = ._pairs.pairFuncs.bind( ._pairs, note); l = ._cache.partListData( part, ._battler).map(func); ._cache.updatePairFuncListPart(note, part, l); } list.concat(l); }.bind( ), []); ._cache.updatePairFuncList(note, list); } defaultResult = ._pairs.default(note, argObj_); result = ._rules.chainedResult(list, note, argObj_, defaultResult); ._cache.updateResult(note, argObj_, result); result; }; ( ) function note, argObj_ if "_isCached" // $._uncachedResult START if this // $._associativeResult START // $._partResults START var this var ( ) function part // $._partResultWithoutCache START // $._uncachedPartResult_ START // $._pairFuncListPartWithoutCache START var this this var this this // $._pairFuncListPartWithoutCache END if 0 return undefined return this // $._uncachedPartResult_ END // $._partResultWithoutCache END // $._partResults END var this return this // $._associativeResult START // $._nonAssociativeResult START // $._pairFuncListWithoutCache START // $._uncachedPairFuncList START var this var ( ) function list, part // $._pairFuncListPartWithoutCache START var this this var this this // $._pairFuncListPartWithoutCache END return this // $._uncachedPairFuncList END // $._pairFuncListWithoutCache END var this return this // $._nonAssociativeResult END // $._uncachedResult END var this if return // $._updatedResultWithCache START // $._uncachedResult START var if this // $._associativeResult START // $._partResults START var this var ( ) function part // $._partResultWithCache START var this if return // $._updatedPartResultWithCache_ START // $._uncachedPartResult_ START // $._pairFuncListPartWithCache START var this var if else // $._updatedPairFuncListPartWithCache START // $._uncachedPairFuncListPart START var this this this this // $._uncachedPairFuncListPart END this // $._updatedPairFuncListPartWithCache END // $._pairFuncListPartWithCache END var undefined if 0 this // $._uncachedPartResult_ END this return // $._updatedPartResultWithCache_ END // $._partResultWithCache END // $._partResults END var this this // $._associativeResult START // $._nonAssociativeResult START // $._pairFuncListWithCache START var this if else // $._updatedPairFuncListWithCache START // $._uncachedPairFuncList START var this var ( ) function list, part // $._pairFuncListPartWithCache START var this var if else // $._updatedPairFuncListPartWithCache START // $._uncachedPairFuncListPart START var this this this this // $._uncachedPairFuncListPart END this // $._updatedPairFuncListPartWithCache END return // $._pairFuncListPartWithCache END this // $._uncachedPairFuncList END this // $._updatedPairFuncListWithCache END // $._pairFuncListWithCache END var this this // $._nonAssociativeResult END // $._uncachedResult END this return // $._updatedResultWithCache END Or this one without comments indicating the starts and ends of the inlined functions: $.result = { (!$gameSystem.satbParam( )) { ( ._rules.isAssociative(note)) { priorities = ._rules.priorities(note); partResults = priorities.map( { func = ._pairs.pairFuncs.bind( ._pairs, note); list = ._cache.partListData( part, ._battler).map(func); (list.length <= ) ; ._rules.chainedResult(list, note, argObj_); }).filter(_SATB.IS_VALID_RESULT); defaultResult = ._pairs.default(note, argObj_); ._rules.chainedResult( partResults, note, argObj_, defaultResult); } priorities = ._rules.priorities(note); list = priorities.reduce( { func = ._pairs.pairFuncs.bind( ._pairs, note); l = ._cache.partListData( part, ._battler).map(func); list.concat(l); }.bind( ), []); defaultResult = ._pairs.default(note, argObj_); ._rules.chainedResult( list, note, argObj_, defaultResult); } cache = ._cache.result_(note, argObj_); (_SATB.IS_VALID_RESULT(cache)) cache; result; ( ._rules.isAssociative(note)) { priorities = ._rules.priorities(note); partResults = priorities.map( { cache = ._cache.partResult_(note, argObj_, part); (_SATB.IS_VALID_RESULT(cache)) cache; c = ._cache.pairFuncListPart_(note, part); list; (c) { list = c; } { func = ._pairs.pairFuncs.bind( ._pairs, note); list = ._cache.partListData( part, ._battler).map(func); ._cache.updatePairFuncListPart(note, part, list); } result = ; (list.length > ) { result = ._rules.chainedResult(list, note, argObj_); } ._cache.updatePartResult(note, argObj_, part, result); result; }).filter(_SATB.IS_VALID_RESULT); defaultResult = ._pairs.default(note, argObj_); result = ._rules.chainedResult( partResults, note, argObj_, defaultResult); } cache = ._cache.pairFuncList_(note), list; (cache) { list = cache; } { priorities = ._rules.priorities(note); list = priorities.reduce( { cache = ._cache.pairFuncListPart_(note, part); l; (cache) { l = cache; } { func = ._pairs.pairFuncs.bind( ._pairs, note); l = ._cache.partListData( part, ._battler).map(func); ._cache.updatePairFuncListPart(note, part, l); } list.concat(l); }.bind( ), []); ._cache.updatePairFuncList(note, list); } defaultResult = ._pairs.default(note, argObj_); result = ._rules.chainedResult(list, note, argObj_, defaultResult); ._cache.updateResult(note, argObj_, result); result; }; ( ) function note, argObj_ if "_isCached" if this var this var ( ) function part var this this var this this if 0 return undefined return this var this return this var this var ( ) function list, part var this this var this this return this var this return this var this if return var if this var this var ( ) function part var this if return var this var if else var this this this this this var undefined if 0 this this return var this this var this if else var this var ( ) function list, part var this var if else var this this this this this return this this var this this this return With just 1 click on $.result. Bear in mind that the actual codebase hasn't changed one bit, it's just that the IDE will display the codes from the original form to the new form. LIV HIV The goal this feature's to keep the codebase in the LIV form, while still letting those who can handle HIV well to be able to read the codebase displayed in the HIV version. It's very unlikely for those who can only handle very well to be able to fathom such a complicated and convoluted method with 73 lines and so many different and implementation details all mixed up together, not to mention the really vast amount of completely needless code duplication that aren't even easy nor simple to spot fast; Those who can handle very well, however, may feel that a 73 line method is so small that they can hold everything inside in their head as a whole very quickly without a hassle. LIV levels of varying abstractions HIV Of course, one doesn't have to show everything at once, so besides the aforementioned feature that inlines everything in the reading mode with just 1 click, the IDE should also support inlining a function at a time. Let's say we're to reveal _uncachedPairFuncListPart: $._updatedPairFuncListPartWithCache = { list = ._uncachedPairFuncListPart(note, part); ._cache.updatePairFuncListPart(note, part, list); list; }; ( ) function note, part var this this return Clicking that method name in the above method should lead to something like this: $._updatedPairFuncListPartWithCache = { func = ._pairs.pairFuncs.bind( ._pairs, note); list = ._cache.partListData( part, ._battler).map(func); ._cache.updatePairFuncListPart(note, part, list); list; }; ( ) function note, part // $._updatedPairFuncListPartWithCache START var this this var this this // $._updatedPairFuncListPartWithCache END this return Similarly, clicking the method name updatePairFuncListPart should reveal the implemention details of that method of this._cache, provided that the IDE can access the code of that class. Such an IDE, if even possible in the foreseeable future, should at least reduce the severity of traversing a deep with tons of small functions for those who can handle very well, if not removing the problem entirely, without forcing those who can only handle very well to deal with , and without the issue of fighting for refactoring in this regard. call stack HIV LIV HIV Summary In general, those who can handle very well will prefer very long functions, as it'll be more effective and efficient to draw the full picture without missing any nontrivial relevant detail that way for such software engineers, while writing and reading very short functions are just going the opposite directions in their perspectives; HIV Those who can only handle very well will prefer very short functions, as it'll be easier and simpler to reason about well-defined abstractions(as long as they don't in nontrivial ways) that way for such software engineers, while writing and reading long functions are just going the opposite directions in their perspectives. LIV leak Unfortunately, very effective and efficient software engineers are generally very intolerant towards extreme ineffectiveness or inefficiencies(especially when those small function abstractions do in nontrivial ways), so all we can do is to try hard. Ideally, we should be able to handle very HIV well while still being very tolerant towards LIV , so we'd be able to work well with codes having all kinds of information volume. leak Combining Information Density With Information Volume Very HID + HIV = Massive Ball Of Complicated And Convoluted Spaghetti Legacy Imagine that you're reading a well-documented 100k line function where almost every line's written like some of the most complex math formulae. I'd guess that even the best of the best software engineers will never ever want to touch this perverted beast again in their lives. Usually such codebase are considered dead and will thus be probably rewritten from scratch. Of course, + isn't always this extreme, as the aforementioned 73 line version of $.result also falls into this category. Even though it'd still be a hellish nightmare for most software engineers to work with if many functions in the codebase are written this way, it's still feasible to refactor them into very high quality code within a reasonably tight budget if we've the highest devotions, diligence and disciplines possible. While such an iron fist approach should only be the last resort, sometimes the it's called for so we should be ready. HID HIV Nevertheless, try to avoid + as much as possible, unless the situation really, really calls for it, like optimizing a massive production codebase to death(e.g.: gameplay codes), or when the problem domain's so chaotic and unstable that no sane nor sensible architecture will survive for even just a short time(pathetic architectures can be way worse than none). If you still want to use this style even when it's clearly unnecessary, you should have the most solid reasons and evidence possible to prove that it's indeed doing more good than harm. HID HIV Very HID + LIV = Otherwise High Quality Codes That Are Hard To Fathom At First For instance, the below codes falls into this category: isValid && (array || []).concat(object || canUseDefault && ); return default Imagine that you're reading a codebase having mostly well-defined and well-documented small functions(but far from being mostly 1 liners) but most of those small functions are written like some the most complex math formulae. While fathoming such codes at first will be very difficult, because the functions are well-documented, those functions will be easy to edit once you've fathomed it with the help of those comments; Because the functions are small enough and well-defined, those functions will be easy to use once you've fathomed how they're being called with the help of those callers who're themselves high quality codes. Of course, + doesn't always mean small short term pains with large long term pleasures, as it's impossible to ensure that none of those abstractions will ever in nontrivial ways. While the codebase will be easy to work with when it only ever has bugs that are either caught by the test suite or have at least some obvious causes, such codebase can still be daunting to work with once it produces rare bugs that are hard to even reproduce, all because of the fact that it's very hard to form the full pictures with every last bit of nontrivial relevant detail of massive codebases having mostly small but very terse functions. HID LIV leak Nevertheless, as long as all things are kept in moderation(one can always try in this regard), + is generally advantageous as long as the codebase's large enough to warrant large scale software architectures and designs(the lifespan of the codebase should also be long enough), but not so large that no one can form the full picture anymore, as the long term pleasures will likely be large and long enough to outweigh short term pains a lot here. HID LIV Very LID + HIV = Excessively Verbose Codes With Tons Of Redundant Boilerplate Think of an extremely verbose codebase having full of boilerplate and exceptionally long functions. Maybe those functions are long because of the verbosity, but you usually can't tell before actually reading them all. Anyway, you'll probably feel that the codebase's just wasting lots of your time once you realize that most of those long functions aren't actually doing much. Think of the aforementioned 28 line verbose Javascript examples having an extremely easy, simple and small terse 1 line counterpart, and think of the former being ubiquitous in the codebase. I guess that even the most verbose software engineers will want to refactor it all, as working with it'd just be way too ineffective and inefficient otherwise. Of course, + isn't always that bad, especially when things are kept in moderation. At least, it'd be nice for most newcomers to fathom the codebase, so codebases written in this style can actually be very beginner-friendly, which is especially important for software teams having very high turnover rates. Even though it's unlikely to be able to work with such codebase effectively nor efficiently no matter how much you've fathomed it due to the heavy verbosity and loads of boilerplate, the problem will be less severe if it's short-lived. Also, writing codes in this style can be extremely fast at first, even though it'll gradually become slower and slower, so this style's very useful in at least prototyping/making PoCs. LID HIV Nevertheless, + shouldn't be used on codebases that'd already be very large without the extra verbosity nor boilerplate, especially when it's going to have a very long life span. Just think of a codebase that can be controlled into the 100k scale all with very terse codes(but still readable), but reaching the 10M scale because of complete refactoring of all those terse codes into tons of verbose codes with boilerplate. Needless to say, almost no one will continue on this road if he/she knows that the codebase will become that large that way. LID HIV Very LID + LIV = Too Many Small Functions With The Call Stacks Being Too Deep For instance, the below codes fall into this category: $._chainedResult = { chainedResultFunc = ._chainedResultFunc(note); ._runChainedResult( list, note, argObj_, initVal_, chainedResultFunc); }; $._chainedResultFunc = { ._rules.chainResultFunc(note); }; $._runChainedResult = { resultFunc(list, note, argObj_, initVal_); }; /* This is the original codes $._chainedResult = function(list, note, argObj_, initVal_) { var chainedResultFunc = this._rules.chainResultFunc(note); return chainedResultFunc(list, note, argObj_, initVal_); }; */ // This is the refactored codes ( ) function list, note, argObj_, initVal_ var this return this ( ) function note return this ( ) function list, note, argObj_, initVal_, resultFunc return // Think of a codebase with less than 100k lines but with already way more than 1k classes/interfaces and 10k functions/methods. It's almost a given that the deepest in the codebase will be so deep that it can even approach the 100 call mark. It's because the only way for very small functions to be very verbose with tons of boilerplate is that most of those small functions aren't actually doing anything meaningful. We're talking about deeply nested / functions which are all indeed doing very easy, simple and small jobs, and tons of interfaces or explicit dependencies having only 1 implementation or concrete (configurable options with only 1 option ever used also has this issue). call stack delegates forwarding dependency Of course, + does have its places, especially when the business requirements always change so abruptly, frequently and unpredicably that even the most reasonable assumptions can be suddenly violated without any reason at all(I've worked with 1 such project). As long as there can still be sane and sensible architectures that can last very long, if the codebase isn't flexible in almost every direction, the software teams won't be able to make it when they've to implement absurd changes with ridiculously tight budgets and schedules. LID LIV And the only way for the codebase to be possible to be so flexible is to have as many well-defined interfaces and seams as possible, as long as everything else is still in moderation. For the newcomers, the codebase will seem to be over nothing already happened, but that's what you'd likely do when you can never know what's invariant. overengineered Nevertheless, + should still be refactored once there are solid reasons and evidences to prove that the codebase can begin to stablize, or the hidden incurred from excessive can quickly accumulate to the point of no return. At that point, even understanding the most common can be almost impossible. Of course, if the codebase can really never stablize, then one can only hope for the best and be prepared for the worst, as such projects are likely , or slowly becoming one. Rare exceptions are that, some codebases have to be this way, like the default RPG Maker MV codebase, due to the business model that any RPG Maker MV user can have any feature request and any RPG Maker MV plugin developer can develop any plugin with any feature. LID LIV technical debt overengineering call stack death marches Summary For instance, doesn't imply nor vice versa, as it's possible to write a very terse long function and a very verbose short function; doesn't imply nor vice versa for the very same reasons. In general, the following largely applies to most codebases, even when there are exceptions: While information density and volume are closely related, there's no strict implications from one to the other, meaning that there are different combinations of these 2 factors and the resultant style can be very different from each other. HID LIV LID HIV Very HID + HIV = Massive Ball Of Complicated And Convoluted Spaghetti Legacy Very HID + LIV = Otherwise High Quality Codes That Are Hard To Fathom At First Very LID + HIV = Excessively Verbose Codes With Tons Of Redundant Boilerplate Very LID + LIV = Too Many Small Functions With The Call Stacks Being Too Deep Teams With Programmers Having Different Styles Very HID/HIV + HID/LIV = Too Little Architecture vs Too Weak To Fathom Codes While both can work with very well, their different capacities and takes on information volume can still cause them to have ongoing significant conflicts. The latter values codebase quality over software engineer mental capacity due to their limits on taking information volume, while the former values the opposite due to their exceptionally strong mental power. HID Thus the former will likely think of the latter as being too weak to fathom the codes and they're thus the ones to blame, while the latter will probably think of the former as having too little architecture in mind and they're thus the ones to blame, as architectures that are beneficial or even necessary for the latter will probably be severe obstacles for the former. Very HID/HIV + LID/HIV = Being Way Too Complex vs Doing Too Little Things While both can work with very well, their different capacities and takes on information density can still cause them to have ongoing significant conflicts. The latter values function simplicity over function capabilities due to their limits on taking information density, while the former values the opposite due to their extremely strong information density decoding. HIV Thus the former will likely think of the latter as doing too little things that actually matter in terms of important business logic as simplicity for the latter means time wasted for the former, while the latter will probably think of the former as being too needlessly complex when it comes to implementing important business logic, as development speed for the former means complexity that are just too high for the latter(no matter how hard they try). Very HID/HIV + LID/LIV = Over-Optimization Freak vs Over-Engineering Freak It's clear that these 2 groups are at the complete opposites - The former preferring of complicated and convoluted over too many small functions with the call stacks being too deep due to the heavy need of optimizing the codebase to death, while the latter preferring the opposite due to the heavy need of making the codebase very flexible. massive balls spaghetti legacy Thus the former will likely think of the latter as freaks while the latter will probably think of the former as freaks, as codebase optimization and flexibility are often somehow at odds with each other, especially when one is heavily done. over-engineering over-optimization Very HID/LIV + LID/HIV = Too Concise/Organized vs Too Messy/Verbose It's clear that these 2 groups are at the complete opposites - The former preferring otherwise high quality codes that are hard to fathom at first over excessively verbose codes with tons of redundant boilerplate due to the heavy emphasis on the large long term pleasures, while the latter preferring the opposite due to the heavy emphasis on the small short term pains. Thus the former will likely think of the latter as being too messy and verbose while the latter will probably think of the former as being too concise and organized, as long term pleasures from the high codebase qualities are often at odds with short term pains of the newcomers fathoming the codebase at first, especially when one is heavily emphasized over the other. Very HID/LIV + LID/LIV = Too Hard To Read At First vs Too Ineffective/Inefficient While both can only work with very well, their different capacities and takes on information density can still cause them to have ongoing significant conflicts. The latter values the learning cost over maintenance cost(the cost of reading already fathomed codes during maintenance) due to their limits on taking information density, while the former values the opposite due to their good information density skill and reading speed demands. LIV Thus the former will likely think of the latter as being too ineffective and inefficient when writing codes that are easy to fathom in the short term but time-consuming to read in the long term, while the latter will likely think of the former as being too harsh to newcomers when writing codes that are fast to read in the long term but hard to fathom in the short term. Very LID/HIV + LID/LIV = Too Beginner Friendly vs Too Flexible For Impossibles While both can only work with very well, their different capacities and takes on information volume can still cause them to have ongoing significant conflicts. The former values codebase beginner friendliness over software flexibility due to their generally lower tolerance on very small functions, while the latter values the opposite due to their limited information volume capacity and high familiarity with very small and flexible functions. LID Thus the former will likely think of the latter as being too flexible towards cases that are almost impossible to happen under the current business requirements due to such codebases being generally harder for newcomers to fathom, while the latter will likely think of the former as being too friendly towards beginners at the expense of writing too rigid codes due to codebases being beginner friendly are usually those just thinking about the present needs. Summary The combinations of these conflicts may be: It seems to me that many coding standard/style conflicts can be somehow explained by the conflicts between HID and LID , and those between HIV and LIV , especially when both sides are being more and more extreme. Very HID/HIV + HID/LIV = Too Little Architecture vs Too Weak To Fathom Codes Very HID/HIV + LID/HIV = Being Way Too Complex vs Doing Too Little Things Very HID/HIV + LID/LIV = Over-Optimization Freak vs Over-Engineering Freak Very HID/LIV + LID/HIV = Too Concise/Organized vs Too Messy/Verbose Very HID/LIV + LID/LIV = Too Hard To Read At First vs Too Ineffective/Inefficient Very LID/HIV + LID/LIV = Too Beginner Friendly vs Too Flexible For Impossibles Conclusions Of course, one doesn't have to go for the , , or extremes, as there's quite some middle grounds to play with. In fact, Nevertheless, it's rather common to work with at least some of the software engineers falling into at least 1 extremes, so we should still know how to work well with them. After all, nowadays most of the real life business codebase are about teamwork but not lone wolves. HID LID HIV LIV I think the best of the best software engineers should deal with all these extremes well while still being able to play with the middle grounds well, provided that such an exceptional software engineer can even exist at all. By exploring the importance of information density, information volume and their relationships, I hope that this article can help us think of some aspects behind codebase readability and the nature of conflicts about it, and that we can be more able to deal with more different kinds of codebase and software engineers better. I think that it's more feasible for us to be able to read codebase with different information density and volume than asking others and the codebase to accommodate with our information density/volume limitations. Also, this article actually implies that readability's probably a complicated and convoluted concept, as it's partially objective at large(e.g.: the existence of consistent formatting and meaningful naming) and partially subjective at large(e.g.: the ability to handle different kinds of information density and volume for different software engineers). Maybe many avoidable conflicts involving readability stems from the tendency that many software engineers treat readability as easy, simple and small concept that are entirely objective. Previously published at https://www.rpgmakercentral.com/blogs/entry/2386-how-information-density-and-volume-affect-codebase-readability/

How To Make Your Codebase More Readable

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

Untitled Story

Bid And Ask Price Thresholds As Technical Indicators

How to learn an existing code base

How to Set Up a Private Blockchain Network with XDC Network Codebase

Speed up your code reviews using ESLint and Prettier

Steps to Fall in Love With an Unfamiliar Codebase

Bid And Ask Price Thresholds As Technical Indicators

How to learn an existing code base

How to Set Up a Private Blockchain Network with XDC Network Codebase

Speed up your code reviews using ESLint and Prettier

Steps to Fall in Love With an Unfamiliar Codebase

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps