Code files

Read an application’s source code, search it, and see what each file is for and how it connects to the rest.

The Files tab is the first of three ways into an application’s code graph – the map Next builds when it reads your source. Here you can browse folders and files, read the code itself, and see the plain-language summary Next wrote for each file.

It is the quickest way to answer questions such as “where does this feature live?” or “what does this folder do?” without asking a developer, and to check that Next has understood the code the way you expect.

Before you start

• Open an application, then select Open code graph under What is attached. See Application detail.
• The version must have finished processing. If it has not, the page says This version has not parsed, so there is no graph to walk yet.
• Use a wide screen. On narrow screens the folder list and the file details panel are hidden.

Understanding the page

The three tabs

Every code graph screen has the same tabs at the top:

The version you are looking at is shown in the top-right corner and carries across all three tabs. Select ← Back to the application to return to the application’s page.

Folders and files

The left-hand panel lists the version’s folders and files. Each repository in the version appears as its own top-level folder.

• The number beside a file is how many definitions were found in it. A definition is a named piece of code, such as a function or a class.
• The dot beside a file or folder shows the state of its summary:

The source and summary panel

The middle panel changes with what you select.

A summary has a What this is for heading, a short description, and sometimes a category and tags. Key symbols are the handful of definitions Next judged a reader needs first.

The file details panel

When a file is open, the right-hand panel shows:

• This file – the file’s purpose, from its summary.
• Definitions – everything found in the file. Select one to jump to it in the source.
• How the file, or the selected definition, connects to the rest of the code, grouped as Calls, Called by, Imports, Imported by, Extends, Extended by, Contains and Defined in. Select any of these to open it.

If a file has no definitions, the panel says it is readable and searchable, but nothing in it was parsed. This is normal for files such as configuration or documentation.

Find a file

The search box above the folder list searches three ways at once.

1. Type at least three characters in Find a file, or what something is for.
2. Review the results, grouped under three headings:
   • By path – files whose path matches what you typed.
   • By meaning – files whose summary matches the idea you described, even if the words differ. For example, “sends invoice emails”.
   • In the code – lines of code containing what you typed.
3. Select a result to open it. A match In the code opens the file at that line.

By meaning works from the summaries, so it only finds files that have been summarised.

Read a file

1. Open folders in the left-hand panel by selecting them.

2. Select a file.

   The source opens in the middle, and its details appear on the right.

3. Select a definition on the right to jump to it in the source.

4. Select a relation, such as an entry under Called by, to open that definition instead.

Write or rewrite a summary

If you have permission to change applications, you can ask Next to write a missing summary or rewrite one that looks wrong.

1. Select a file or folder.
2. Select Write it if there is no summary yet, or Rewrite beside an existing one.

Rewriting a file’s summary also rewrites the summaries of every folder above it, because a folder’s summary is written from its contents.

What to expect

• Very large files are shown without syntax highlighting, with the message Syntax highlighting is off for this file because of its size.
• If a summary was skipped, the panel says why, rather than leaving it looking unfinished.
• If summaries are off, the panel says Summaries are off, so nothing describes this file.
• If the code graph cannot be reached, the source and definitions are unavailable, but summaries still show.

Good to know

• Agents read the same summaries. If a summary is misleading, agent packs may choose the wrong files. Rewriting it helps both people and agents.
• Take the tour. The help (?) menu in the top bar replays this tab’s guided tour.

Related pages

• Code map
• Code relations
• Application detail
• Applications
• Governance: Applications