Skip to content

docs: resolve TODOs in introduction (#1264) #1265

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Arinapakalova wants to merge 2 commits into
base: master
Choose a base branch
from
Open

docs: resolve TODOs in introduction (#1264) #1265

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4c3c997
docs: resolve TODOs in introduction (#1264)
Arinapakalova Jul 12, 2026
394c149
Update wp/references.bib
Arinapakalova Jul 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions wp/references.bib
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1249,3 +1249,20 @@ @inproceedings{Vaucher2009TrackingDS
title = {{Tracking Design Smells: Lessons From a Study of God Classes}},
year = {2009},
}

`@techreport`{ISO25010,
title = {Systems and software engineering -- Systems and software Quality Requirements and Evaluation (SQuaRE) -- Product quality model},
institution = {International Organization for Standardization},
number = {ISO/IEC 25010:2023},
year = {2023},
url = {https://www.iso.org/standard/78176.html}
}
}

@book{Leveson2011,
title = {Engineering a Safer World: Systems Thinking Applied to Safety},
author = {Leveson, Nancy},
year = {2011},
publisher = {MIT Press},
url = {https://mitpress.mit.edu/9780262016629/engineering-a-safer-world/}
}
14 changes: 6 additions & 8 deletions wp/sections/introduction.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,16 +24,16 @@
analyze, modify, and adapt given software \citep{Mohammadi2013AnAO}.

Functional quality aspects are typically quite susceptible to formal definition
and quantification.
% (\todo: examples!!).
and quantification. For example, metrics such as defect density measured per
thousand lines of code (KLOC), code coverage percentages, or pass/fail rates
of functional test suites provide clear, quantifiable measures of functional correctness.
Comment on lines +27 to +29

@coderabbitai coderabbitai Bot Jul 12, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Qualify these metrics as indicators, not measures of correctness.

Defect density and code coverage are quantifiable, but neither directly establishes functional correctness. Please describe them as indicators of functional quality and add supporting citations for the metric claims.

Proposed wording 
- metrics such as defect density measured per 
- thousand lines of code (KLOC), code coverage percentages, or pass/fail rates 
- of functional test suites provide clear, quantifiable measures of functional correctness. 
+ metrics such as defect density per thousand lines of code (KLOC), code coverage,
+ and functional-test pass rates provide quantifiable indicators of functional
+ quality, but none alone establishes functional correctness.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
and quantification. For example, metrics such as defect density measured per
thousand lines of code (KLOC), code coverage percentages, or pass/fail rates
of functional test suites provide clear, quantifiable measures of functional correctness.
and quantification. For example, metrics such as defect density per
thousand lines of code (KLOC), code coverage, and functional-test pass rates
provide quantifiable indicators of functional quality, but none alone establishes
functional correctness.
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@wp/sections/introduction.tex` around lines 27 - 29, Revise the metrics
discussion in the introduction around the examples of defect density, code
coverage, and functional test pass rates to describe these values as indicators
of functional quality rather than direct measures of functional correctness. Add
appropriate supporting citations for the claims about these metrics, while
preserving the surrounding discussion.

Functional quality is also an essential
requirement in any domain of software development. On the other hand,
maintainability is a lot less straightforward to formally specify or quantify.
%\todo: refs.
maintainability is a lot less straightforward to formally specify or quantify
\citep{ISO25010}.
Comment on lines +32 to +33

@coderabbitai coderabbitai Bot Jul 12, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Locate the file and inspect the relevant section with line numbers.
git ls-files 'wp/sections/introduction.tex' 'wp/**/*.bib' 'wp/**/references*' | cat

echo
echo '--- introduction excerpt ---'
sed -n '1,120p' wp/sections/introduction.tex | cat -n

echo
echo '--- ISO 25010 bibliography references ---'
rg -n -C 2 'ISO25010|25010|ISO/IEC 25010' wp -g '*.bib' -g '*.tex'

Repository: cqfn/aibolit

Length of output: 6391

Use a source that supports the quantification claim
ISO/IEC 25010 defines the product quality model, but it doesn’t substantiate the comparison that maintainability is “less straightforward to formally specify or quantify.” Narrow the sentence to what the standard states, or add a source that explicitly contrasts maintainability with more directly measurable qualities.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@wp/sections/introduction.tex` around lines 32 - 33, Revise the sentence
containing “maintainability is a lot less straightforward to formally specify or
quantify” so it only makes claims directly supported by ISO25010, or add a
citation that explicitly supports the comparison. Preserve the surrounding
discussion while removing or narrowing the unsupported quantification claim.

Also, in certain applications it appears less important than
functional correctness, although in the business domain it is recognized as an
essential property.
% (\todo: ref).
essential property \citep{Leveson2011}.
Comment on lines 34 to +36

@coderabbitai coderabbitai Bot Jul 12, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Inspect the target section with line numbers
sed -n '1,120p' wp/sections/introduction.tex | cat -n

# Find the Leveson citation entry and nearby bibliography context
rg -n "Leveson2011|Leveson" -S wp || true

Repository: cqfn/aibolit

Length of output: 5470

🏁 Script executed:

#!/bin/bash
set -euo pipefail

sed -n '1258,1272p' wp/references.bib | cat -n

Repository: cqfn/aibolit

Length of output: 518

Change “business domain” to “safety-critical systems”
Leveson’s book is about engineering safer systems and safety-critical applications, so the current wording overstates what the citation supports. Reword this sentence to match that context, or cite a source that discusses maintainability in the business domain.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@wp/sections/introduction.tex` around lines 34 - 36, Update the sentence
around the Leveson2011 citation in the introduction to replace “business domain”
with wording about safety-critical systems or applications, preserving the
intended contrast with functional correctness and the existing citation.

As a result, there is currently a lot more
research and practical tools addressing functional quality aspects of code than
maintainability \citep{Overview_Static_Code_Analysis_in_Software_Development}.
Expand Down Expand Up @@ -66,8 +66,6 @@





% This document explains how Aibolit works and what makes it novel and
% different from other static analyzers (Section~\ref{sec:method}).
% We further show how Aibolit can be extended
Expand Down
Loading