Visual Patterns in Source Code Arrangement

source code arrangement is a matter of debate. what would you consider a good practice for the number of lines of code per file, the number of files per directory, the total number of files in a project? to help answer these questions, one must see the big picture: how does a project code look from a bird's eye view? codeflowers are a way to look at code layouts in a graphical way. using it on various projects, you quickly see some visual patterns emerge.

the mistletoe

one very large file (greater than 500 lines of code) among a tree structure of normal size files. this files doesn't look at its place, i call it the mistletoe . whether it's a css or a list of utility methods, dealing with large files is often a developer's nightmare. it's a good start for a refactoring session: split the mistletoe into several files, it will disappear.

the dandelion

a directory with a lot (more than 30) very small files. it's so familiar that you want to blow on it to scatter the seeds: i call it the dandelion . you often find dandelions in internationalized projects, where translation files are numerous and lie in the same directory. they may not be problematic, until the number of files becomes really too big, and developers find it hard to find the one they're looking for.

twigs

several thin branches, not many leafs: meet the twigs . this is a deep directory structure that requires a lot of clicks to browse, where the number of files per directory (one or two) is suboptimal. i see this pattern a lot in psr-0 projects, because the class naming rule imposes a deep directory structure. try to regroup leafs on a single branch to make your fellow developers happier.

twin branches

two branches that look the same: this is often caused by a test class layout following the library layout - and it's a good practice. don't panic if you see twin branches , they make the tester's life easier.

grapes

many very large files attached to the same branch: that's the grapes . the files are so big and so numerous that the leafs overlap on the visualization. it makes it difficult to tell one file from the other. it's equally difficult for developers to work with such code layouts. this is often representative of aging libraries, where not enough time was spent on refactoring. but if you see only grapes in a codeflower, it may also be because you're looking at a program which uses a very verbose language.

the sunflower

a very large flower with regular petals, and several directory levels, is a pattern i call the sunflower . you may find it in projects where a library is declined several times, or where several sets of data using the same layout are required. it's not a problem as long as the directories composing it are properly named.

did you see other patterns?

if you spot other patterns, feel free to share them here. code layout is a matter of taste of course, but there are common practices that are interesting to discuss.