# [Оформление кода](https://en.wikipedia.org/wiki/Indentation_style)


[TOC]

## Оформление в виде блок-схемы
Для представления программного кода и объяснения его функционирования следует либо вместе с кодом представлять его [блок-схему](https://en.wikipedia.org/wiki/Flowchart) - смотри пример ниже, либо выполнить его [**форматирование, отражающее важные зависимости**](#Оформление-кода-с-помощью-отступов) между участками кода ([смотри пример оформления кода с отступами](#Пример-оформления-кода-с-отступами)) :
<img src=https://upload.wikimedia.org/wikipedia/commons/0/06/For-loop-diagram.png height=400>
или следующий пример, выполненный средствами языка MD:

st=>start: Start:>http://flowchart.js.org[blank]
e=>end: MyEnd:>https://hackmd.io/@ArthMax/Code/edit

i=>inputoutput: input something...
op1=>operation: My Operation
sub1=>subroutine: My Subroutine
cond=>condition: Yes or No?:>http://www.google.com
io=>inputoutput: output something...
para=>parallel: parallel tasks

st->i->op1->cond
            cond(yes)->io->e
            cond(no)->para
                      para(path1, bottom)->sub1(bottom)->e
                      para(path2, top)->op1

## Оформление с помощью mermaid диаграмм

graph TD
    A((Start))
     B{Is it?}
      C[OK]
    A --> B
          B -- Yes --> C
                       C --> D[Rethink]
                             D --> B
          B -- No ----> E(End)

## Пример блок-схемы с вызовом функции

#ifdef GL_ES
precision mediump float;
#endif

uniform float u_time;

    float mytime(float x){
                return x/10.0;
    }
    
void main() {
         float t = mytime(u_time);
          gl_FragColor = vec4(mod(t,1.0), 0.5, 0.0, 1.0);
}


## [Оформление кода с помощью отступов](#Оформление-кода-с-помощью-отступов)

Требования к форматированию кода
1) Отражение [**зависимости строк кода по данным**](https://ru.wikipedia.org/wiki/%D0%97%D0%B0%D0%B2%D0%B8%D1%81%D0%B8%D0%BC%D0%BE%D1%81%D1%82%D1%8C_%D0%B4%D0%B0%D0%BD%D0%BD%D1%8B%D1%85) - сдвиг вправо на 1 пробел относительно строки, от которой зависит текущая строка (*контрольным признаком таких зависимостей является невозможность перестановки строк кода без нарушения правильной работы программы*)
2) Отражение [**зависимости участков кода по управлению**](https://ru.wikipedia.org/wiki/%D0%97%D0%B0%D0%B2%D0%B8%D1%81%D0%B8%D0%BC%D0%BE%D1%81%D1%82%D1%8C_%D0%B4%D0%B0%D0%BD%D0%BD%D1%8B%D1%85#:~:text=%D0%B4%D0%B8%D0%BD%D0%B0%D0%BC%D0%B8%D1%87%D0%B5%D1%81%D0%BA%D0%B8%20%D0%B0%D0%BF%D0%BF%D0%B0%D1%80%D0%B0%D1%82%D0%BD%D1%8B%D0%BC%D0%B8%20%D1%81%D1%80%D0%B5%D0%B4%D1%81%D1%82%D0%B2%D0%B0%D0%BC%D0%B8.-,%D0%97%D0%B0%D0%B2%D0%B8%D1%81%D0%B8%D0%BC%D0%BE%D1%81%D1%82%D0%B8%20%D0%BF%D0%BE%20%D1%83%D0%BF%D1%80%D0%B0%D0%B2%D0%BB%D0%B5%D0%BD%D0%B8%D1%8E,-%5B%D0%BF%D1%80%D0%B0%D0%B2%D0%B8%D1%82%D1%8C%20%7C) (в операторах if()..., for()..., do{...}..., while()... и т.п.) -- сдвиг вправо не менее чем на 2 пробела управляемого блока относительно строки с заголовком оператора
3) Отражение [**зависимости функций друг от друга (функциональные зависимости)**](https://ru.wikipedia.org/wiki/%D0%93%D1%80%D0%B0%D1%84_%D0%B2%D1%8B%D0%B7%D0%BE%D0%B2%D0%BE%D0%B2) - сдвиг вправо на 4 пробела функций относительно зависимых функций
4) Выделение [**функций, обрабатывающих события,**](https://en.wikipedia.org/wiki/Event_(computing)) (а также функций-колбэков и асинхронных функций) - сдвиг вправо не менее, чем на 8 пробелов от левого края с комментарием ```////----------```, подчеркивающим характер функции - обработчика события
5) Отделение одних, **непосредственно связанных по смыслу**, участков кода от других пустыми строками (например, отделение объявлений переменных от операций ввода)
6) **Комментарии** непосредственно связанных по смыслу участков кода
7) Использовать **аналогичный подход для форматирования наборов структур и классов**, в частности, отношения включения-композиции ([*has*](https://en.wikipedia.org/wiki/Has-a)) и наследования ([*is*](https://en.wikipedia.org/wiki/Is-a)) - рассматривать как отношения зависимости по метаданным, отношения использования (*use*) функционала других классов - рассматривать как отношения функциональных зависимостей.

:::info
*Примечание*. Для сложных, рекурсивно завязаных друг на друга структур данных, классов и функций, (например, при использовании паттернов проектирования), следует выделить осмысленные остовные деревья зависимостей и использовать для них вышеуказанные правила с указанием точек выхода в структурную рекурсию.
:::

## [Пример оформления кода с отступами](#Пример-оформления-кода-с-отступами)

#ifdef GL_ES
precision mediump float;
#endif

uniform float u_time;

    float mytime(float x){
                return x/10.0;
    }
    
void main() {
         float t = mytime(u_time);
          if(t>60.0){
             t=60.0;
          }
           gl_FragColor = vec4(mod(t,1.0), 0.5, 0.0, 1.0);
}

:::info
В этом примере форматирования кода строки {7,8,9}, описывающие функцию mytime(), сдвинуты на 4 пробела относительно функции main(), поскольку main() *функционально зависит* от mytime() и вызов функции mytime() происходит во время работы функции main() в строке 12.

Строка 13 (заголовок оператора if) сдвинута на 1 позицию относительно строки 12, поскольку результат работы оператора присваивания (значение переменной t) в строке 12 используется для проверки истинности условия в строке 13. Между строками 12 и 13, таким образом, есть *зависимость по данным*.

Строка 14 сдвинута на 3 позиции относительно строки 13, поскольку так отражается зависимость тела условного оператора по управлению от заголовка условного оператора в строке 13. Между строками 13 и 14, таким образом, есть *зависимость по управлению*.

Строка 16 сдвинута на 1 позицию относительно строк 13, 15, поскольку результат работы оператора присваивания в строке 14 (в теле условного оператора) может повлиять на значение цвета в строке 16. Между результатом работы условного оператора (строки 13--15) и строкой 16, таким образом, есть *зависимость по данным* (более слабая, чем зависимость между строчками 12 и 13).
:::


# [Ссылки](#Ссылки)

1) [Зависимость данных](https://ru.wikipedia.org/wiki/%D0%97%D0%B0%D0%B2%D0%B8%D1%81%D0%B8%D0%BC%D0%BE%D1%81%D1%82%D1%8C_%D0%B4%D0%B0%D0%BD%D0%BD%D1%8B%D1%85)
2) [Data_dependency](https://en.wikipedia.org/wiki/Data_dependency)
3) [Dependence_analysis](https://en.wikipedia.org/wiki/Dependence_analysis)
4) [Flowchart](https://en.wikipedia.org/wiki/Flowchart)
5) [Стиль о́тступов (индентация)](https://ru.wikipedia.org/wiki/%D0%9E%D1%82%D1%81%D1%82%D1%83%D0%BF_(%D0%BF%D1%80%D0%BE%D0%B3%D1%80%D0%B0%D0%BC%D0%BC%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5))
6) [Indentation_style](https://en.wikipedia.org/wiki/Indentation_style)
7) [Secondary_notation](https://en.wikipedia.org/wiki/Secondary_notation)
8) [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html)
9) [A systematic mapping study of source code representation for deep learning in software engineering](https://ietresearch.onlinelibrary.wiley.com/doi/full/10.1049/sfw2.12064)
10) [A Mocktail of Source Code Representations](https://arxiv.org/pdf/2106.10918.pdf)
11) [Measuring the Impact of Code Dependencies on
Software Architecture Recovery Techniques](https://www.cs.purdue.edu/homes/lintan/publications/archrec-tse17.pdf)
12) [Precise Learning of Source Code Contextual Semantics via
Hierarchical Dependence Structure and Graph Attention Networks](https://arxiv.org/pdf/2111.11435.pdf)
13) https://en.wikipedia.org/wiki/Static_single-assignment_form
14) https://en.wikipedia.org/wiki/Reaching_definition
15) https://en.wikipedia.org/wiki/Use-define_chain
16) https://en.wikipedia.org/wiki/Call_graph
17) [Граф вызовов](https://ru.wikipedia.org/wiki/%D0%93%D1%80%D0%B0%D1%84_%D0%B2%D1%8B%D0%B7%D0%BE%D0%B2%D0%BE%D0%B2)
18) [Dependency graphs for program analysis](https://uditagarwal.in/understanding-dependency-graphs-for-program-analysis/)
19) [Why Your Code Is A Graph](https://blog.shiftleft.io/why-your-code-is-a-graph-f7b980eab740)
20) [Dependency Graph in Compiler Design](https://www.geeksforgeeks.org/dependency-graph-in-compiler-design/)
21) [Getting Control Flow Graph from ANSI C code](https://stackoverflow.com/questions/16393985/getting-control-flow-graph-from-ansi-c-code)
22) [Generate a dependency diagram for c++ codes/projects](https://stackoverflow.com/questions/67240232/generate-a-dependency-diagram-for-c-codes-projects?noredirect=1&lq=1)
23) [cflow](https://lists.gnu.org/archive/html/info-gnu/2021-12/msg00013.html)
24) https://www.graphviz.org/theory/
25) [ConfVideo "Dependency management in C++"](https://youtu.be/dJpAppmRWVI)