Style/ru: Difference between revisions

From KolibriOS wiki
Jump to navigation Jump to search
No edit summary
No edit summary
 
(9 intermediate revisions by 5 users not shown)
Line 1: Line 1:
== Стиль оформления ==
== Правила SVN для ядра ==
* Табуляции запрещены.
* Метки должны идти в отдельной строке от кода (но могут быть в одной строке с данными).
* Строка начинается с восьми пробелов. Далее идёт имя команды или макроса. Если имя короче восьми символов, то оно дополняется пробелами до восьми символов; если нет, то далее идёт один пробел. Потом опционально идут аргументы, разделённые запятой и одним пробелом после неё.
* Префиксы lock/rep[z|e|nz|ne] считаются логическим целым с последующей командой и отделяются одним пробелом.
* Все файлы с кодом должны обладать служебным свойством 'svn:eol-style' со значением 'native'.
* Все текстовые файлы должны быть в кодировке UTF-8 без BOM.


Рекомендации по оформлению кода.
= Asmxygen =


При написании процедур необходимо перед процедурой указывать входные, выходные параметры, так же указывать какие регистры изменяются.
В ядре присутствует doxygen документация. Синтаксис документации идентичен таковой в обычном doxygen за исключением следующих ньюансов:
* Если функция не возвращает значений и не принимает параметров - в доксиген комментарии следует указать `@returns Nothing`
* Для удаления функции из документации можно воспользоваться директивой `@dont_give_a_doxygen`


;in: eax = pointer
== Рекомендации ==
;     ebx = PID
* Переменные должны иметь либо исчерпывающее название без сокращений, либо комментарий.
;out: eax = return code in (0,-1)
* То же самое желательно применять и к меткам, а так же располагать их в отдельной строке без отступа.
;destroys eax
* При написании процедур необходимо описывать её назначение, входные и выходные параметры, изменяемые регистры:
;================================
<syntaxhighlight lang="asm">; @brief Doing job.
subrutine:
; @param eax Some data
; @param ebx Some pointer
; @returns Some result
; @warning Destroys ebx register.
subroutine:</syntaxhighlight>


При написании процедур очень полезно комментировать их способом, показанным ниже.
[[Category:Кодинг]]
 
Тогда даже человек, только начинающий изучать ассемблер, сразу поймёт, что далет данная функция. И наоборот, даже самому опытному программисту может понадобится некторое время просто на понимание того, что делает данная функция.
 
;-----------------------------------------------------------------------------
proc key.ctrl_o ;///// ENTER OPEN FILENAME ///////////////////////////////////
;-----------------------------------------------------------------------------
  ...
  ...
  ...
endp
 
Если Вы вносите изменения или добавление в программу, неважно каких размеров, полезно как-то помечать добавленный код, попутно описывая, какую операцию он выполняет. Тогда потом никто не  будет недоумевать "А это здесь откуда и что оно вообще делает?".
 
Делать это можно так, как показано ниже:
 
;// diamond [ (convert size from decimal representation to dword)
;--    mov    edx,dword[@PARAMS+1]
mov esi,@PARAMS+1
xor edx,edx
xor eax,eax
    @@: lodsb
test al,al
jz @f
lea edx,[edx*4+edx]
lea edx,[edx*2+eax-'0']
jmp @b
    @@:
;// diamond ]
 
[[Category:Coding]]

Latest revision as of 17:44, 8 July 2021

Правила SVN для ядра

  • Табуляции запрещены.
  • Метки должны идти в отдельной строке от кода (но могут быть в одной строке с данными).
  • Строка начинается с восьми пробелов. Далее идёт имя команды или макроса. Если имя короче восьми символов, то оно дополняется пробелами до восьми символов; если нет, то далее идёт один пробел. Потом опционально идут аргументы, разделённые запятой и одним пробелом после неё.
  • Префиксы lock/rep[z|e|nz|ne] считаются логическим целым с последующей командой и отделяются одним пробелом.
  • Все файлы с кодом должны обладать служебным свойством 'svn:eol-style' со значением 'native'.
  • Все текстовые файлы должны быть в кодировке UTF-8 без BOM.

Asmxygen

В ядре присутствует doxygen документация. Синтаксис документации идентичен таковой в обычном doxygen за исключением следующих ньюансов:

  • Если функция не возвращает значений и не принимает параметров - в доксиген комментарии следует указать `@returns Nothing`
  • Для удаления функции из документации можно воспользоваться директивой `@dont_give_a_doxygen`

Рекомендации

  • Переменные должны иметь либо исчерпывающее название без сокращений, либо комментарий.
  • То же самое желательно применять и к меткам, а так же располагать их в отдельной строке без отступа.
  • При написании процедур необходимо описывать её назначение, входные и выходные параметры, изменяемые регистры:
; @brief Doing job.
; @param eax Some data
; @param ebx Some pointer
; @returns Some result
; @warning Destroys ebx register.
subroutine:
Retrieved from "http://wiki.kolibrios.org/index.php?title=Style/ru&oldid=5862"