changed a year ago  
Published Linked with GitHub

Оформление кода

Оформление в виде блок-схемы

Для представления программного кода и объяснения его функционирования следует либо вместе с кодом представлять его блок-схему - смотри пример ниже, либо выполнить его форматирование, отражающее важные зависимости между участками кода (смотри пример оформления кода с отступами) :

Image Not Showing Possible Reasons
  • The image file may be corrupted
  • The server hosting the image is unavailable
  • The image path is incorrect
  • The image format is not supported
Learn More →

Image Not Showing Possible Reasons
  • The image file may be corrupted
  • The server hosting the image is unavailable
  • The image path is incorrect
  • The image format is not supported
Learn More →

или следующий пример, выполненный средствами языка 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. Отражение зависимости строк кода по данным - сдвиг вправо на 1 пробел относительно строки, от которой зависит текущая строка (контрольным признаком таких зависимостей является невозможность перестановки строк кода без нарушения правильной работы программы)
  2. Отражение зависимости участков кода по управлению (в операторах if()…, for()…, do{…}…, while()… и т.п.) – сдвиг вправо не менее чем на 2 пробела управляемого блока относительно строки с заголовком оператора
  3. Отражение зависимости функций друг от друга (функциональные зависимости) - сдвиг вправо на 4 пробела функций относительно зависимых функций
  4. Выделение функций, обрабатывающих события, (а также функций-колбэков и асинхронных функций) - сдвиг вправо не менее, чем на 8 пробелов от левого края с комментарием ////----------, подчеркивающим характер функции - обработчика события
  5. Отделение одних, непосредственно связанных по смыслу, участков кода от других пустыми строками (например, отделение объявлений переменных от операций ввода)
  6. Комментарии непосредственно связанных по смыслу участков кода
  7. Использовать аналогичный подход для форматирования наборов структур и классов, в частности, отношения включения-композиции (has) и наследования (is) - рассматривать как отношения зависимости по метаданным, отношения использования (use) функционала других классов - рассматривать как отношения функциональных зависимостей.

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

Пример оформления кода с отступами


















#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);
}

В этом примере форматирования кода строки {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. Зависимость данных
  2. Data_dependency
  3. Dependence_analysis
  4. Flowchart
  5. Стиль о́тступов (индентация)
  6. Indentation_style
  7. Secondary_notation
  8. Google C++ Style Guide
  9. A systematic mapping study of source code representation for deep learning in software engineering
  10. A Mocktail of Source Code Representations
  11. Measuring the Impact of Code Dependencies on
    Software Architecture Recovery Techniques
  12. Precise Learning of Source Code Contextual Semantics via
    Hierarchical Dependence Structure and Graph Attention Networks
  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. Граф вызовов
  18. Dependency graphs for program analysis
  19. Why Your Code Is A Graph
  20. Dependency Graph in Compiler Design
  21. Getting Control Flow Graph from ANSI C code
  22. Generate a dependency diagram for c++ codes/projects
  23. cflow
  24. https://www.graphviz.org/theory/
  25. ConfVideo "Dependency management in C++"
Select a repo