What is navigability?
I made up this word in the same manner as read-ability. If readability “is the ease with which a reader can understand a written text” (Wikipedia). Navigability is the ease with which a reader can navigate a written text.
For example, traditional printed texts have the following navigation patterns:
- Start and end - we can read the book from start to end
- Table of contents, chapters
- Alphabetical index
Online texts have (in addition to traditional texts)
- hyperlinks
- text search
Navigability contributes to readability. Easier it is to navigate text easier it is read text.
Navigability in code
Navigability in code is a special case. If we take traditional text it’s navigability is predefined, for example, table of contents for a book. But navigability in code will vary depending on IDE, on task, on a reader, on programming language, etc.
Let’s talk about some popular navigation solutions for code.
File structure
One of the attempts to improve navigability is by introducing a file structure. For example:
/src
/tests
/utils
This works well if there is time tested convention, for example, Ruby on Rails.
The idea of putting code in separate files is widely adopted, but there is no research that proves it makes navigation easy.
The downside of files is that you need to keep the context in memory when you jump between files.
Jump to definition
Some IDEs and text editors allow to trace the origin of the symbol (variable, function, etc.). The effectiveness of this varies depending on PL. As well it will break in case of “code indirections”, for example, callbacks, dependency injections, etc.
Text search
As well sometimes called grep-ability. I call this strategy fallback, e.g. people use it when everything else failed, for example:
- when “jump to definition” doesn’t work, we can search for this symbol instead
- when we failed to follow file structure we can try to search some keyword (phrase on the screen, the path in URL, etc)
Debugging
Sometimes when everything else failed we can use debugging methodologies to find a way around in the code. If this is the case it means navigability is very poor.
Reasons to navigate
I guess the way we navigate through code as well depends on the reason why we want to navigate through code. For example,
- I need to change behaviour (look, text, etc) of some code, where is code responsible for this behaviour?
- I edit function (component etc) where is it used?
- See I am a puts debuggerer for other examples
Your thoughts?
Do you know other code navigation patterns I missed?
Top comments (12)
The word already exists - Navigability
Yes, I saw this word. But according to oxford dictionary navigability - the degree to which a river, lake, etc. is wide enough for ships and boats to sail on. I wasn't sure if I can reuse it here
Yes, in that usage, it is the degree to which a river etc. can be navigated - i.e. how easy it is for the ships captain to navigate their way through. It's exactly the word you need - but you're using it in the sense of how easy some code is to navigate by someone who is reading it
My favourite solution is to have component based folders if possible.
Foo/
Foo.js
Foo.scss
Foo.test.js
I've worked on codebases where file "type" organisation is used. It's also fine, but since related files are scattered in multiple places it just takes a bit longer to find them, create them, and also make sure you've done all necessary changes each time.
For searching, I just use the IDE to search by filename.
+1
We also recently started putting all files in one folder, especially JS and CSS files. We started off with a different folder for all of the CSS. Finding the right CSS file is particulartly tedious.
There is the bookmark functionality in most editors, where you can keep important positions in files. I do this while working on a certain feature and remove them when I’m done. I like to have long files rather than lots of files, and this makes jumping around easier.
I prefer more files over longer files. Its easier to merge. The syntax colorizer and other editor tools (and partial builds) are faster. And its faster to reason about as a whole.
But cant avoid the large files, so one thing ive always wanted in editors are the ability to drag a single block of code into its own virtual editor. A kinda focus mode. No accidentally scrolling away. And a search that only find text within that block of code.
Emacs narrowing welcomes you.
This seems like tool issue. There are editors which can be really fast (something native instead of electron based). There are projects like tree sitter which can help here.
Bigger number of file require context switch when jumping between files while reading files.
Nice idea)
I didn't even thing about the colorizer since I'm using a B/W color-scheme. But yes, usually it's not a problem even with VSCode. Only when opening compiled/minified files by accident.
Indeed bookmarks is one more navigation pattern known since printed media
I'd love to see data flow or call graph visualization showing the composition of an endpoint in one swoop.
Haskell has Hoogle which finds functions by signatures.