mirror of
https://github.com/lexborisov/Modest
synced 2024-11-21 21:31:25 +03:00
309 lines
17 KiB
Markdown
309 lines
17 KiB
Markdown
# Общее положение
|
||
|
||
### Основное правило
|
||
|
||
Код проекта должен быть понятным и легко читаемым. Конечно, всё это относительно, но нужно стараться придерживаться этому правилу. Не нужно мудрить, нам же поддерживать этот код.
|
||
|
||
### Структура проекта
|
||
|
||
Проект модульный. Теоретически каждый модуль может быть собран отдельно от всего проекта. Модули могут иметь между собой зависимости. К примеру, в данный момент все модули зависимы от модуля `mycore`.
|
||
|
||
Все существующие модули находятся в директории `/source/` проекта Modest.
|
||
|
||
### Зависимости
|
||
|
||
Проект развивается без внешних зависимостей. Не то чтобы мне по фану писать не раз уже всеми написанные алгоритмы, вроде AVl Tree, Binary Search Tree и так далее, мне важно использовать собственный подход в создании объектов и управлении памятью.
|
||
|
||
Так же, большенство реализованных алгоритмов не являются "чистыми", логика их как-то изменена/оптимизирована под нужды проекта.
|
||
|
||
Я не против зависимостей, но зачастую всё что нужно проекту легче написать самостоятельно чем адаптировать чей-то код, лицензии.
|
||
|
||
### Платформозависимый код
|
||
|
||
Не смотря на тот факт, что проект пишется на чистом Си (C99) без внешних зависимостей реализация некоторых функций зависит от конкретной платформы. А именно: многопоточность, таймеры, ввод-вывод, блокировки (spinlock, mutex).
|
||
|
||
Для этого реализован отдельный модуль `myport` который имеет свою собственную структуру и правила сборки отличные от остальных модулей.
|
||
|
||
### Статусы
|
||
|
||
Если внутри какой-либо функции что-то может пойти "не так" то функция должна об этом однозначно сообщить.
|
||
|
||
Существует общий для всех тип `mystatus_t` (`int`) опредленный в `mycore/myosi.h`.
|
||
Каждый модель проекта Modest определяет свой диапозон статусов. Для примера,
|
||
|
||
```C
|
||
/*
|
||
...
|
||
mycore 000000..008fff; MyCORE_STATUS_OK == 0x000000
|
||
myhtml 009000..0093ff; MyHTML_STATUS_OK == 0x000000
|
||
...
|
||
*/
|
||
```
|
||
С полным списком можно ознакомится в файле `mycore/myosi.h`.
|
||
|
||
Любая функция любого модуля может возвращать любой статус. К примеру, функции из модуля `myhtml` могут возвращать статус `MyCORE_STATUS_ERROR_MEMORY_ALLOCATION`.
|
||
|
||
Два главных правила при работе со статусами:
|
||
|
||
1. Если статус равен нолю (0) то значит всё хорошо, иначе что-то пошло не так.
|
||
2. Необходимо возвращать реальные статусы. То есть, если память не выделена то вернуть `MyCORE_STATUS_ERROR_MEMORY_ALLOCATION `, а не какой-нибудь фейковый 0x100.
|
||
|
||
Перечисления (enum) статусов для конкретного модуля лучше всего держать в файле `myosi.h` в корне модуля. Для примера, `/source/myhtml/myosi.h`.
|
||
|
||
### Версии модулей
|
||
|
||
Каждый модуль должен содержать информацию о своей версии в заголовочном файле `myosi.h` в корне модуля. Для примера, `/source/myhtml/myosi.h`.
|
||
|
||
Шаблон:
|
||
|
||
```C
|
||
#define <ИМЯ-МОДУЛЯ>_VERSION_MAJOR 4
|
||
#define <ИМЯ-МОДУЛЯ>_VERSION_MINOR 0
|
||
#define <ИМЯ-МОДУЛЯ>_VERSION_PATCH 2
|
||
|
||
#define <ИМЯ-МОДУЛЯ>_VERSION_STRING MyCORE_STR(<ИМЯ-МОДУЛЯ>_VERSION_MAJOR) MyCORE_STR(.) MyCORE_STR(<ИМЯ-МОДУЛЯ>_VERSION_MINOR) MyCORE_STR(.) MyCORE_STR(<ИМЯ-МОДУЛЯ>_VERSION_PATCH)
|
||
```
|
||
|
||
### Именование функций
|
||
|
||
Для создания имени функции используется шаблон:<br>
|
||
`<название-проекта>_<путь-к-файлу>_<название-файла>_<название>(...);`
|
||
|
||
Для примера возмём функцию `mycore_utils_avl_tree_init(...)`:<br>
|
||
Найти её легко в `/source/mycore/utils/avl_tree.c`
|
||
|
||
Бывают исключения, но они обычно от лени.
|
||
|
||
### Функции Конструкторы/Деструкторы
|
||
|
||
Для API создания, инициализации, очистки, удаления объектов используется следующий шаблон:
|
||
|
||
```C
|
||
<имя-структуры> * <префикс-функции>_create(void);
|
||
mystatus_t <префикс-функции>_init(<имя-структуры>* obj);
|
||
void <префикс-функции>_clean(<имя-структуры>* obj);
|
||
void <префикс-функции>_clean_all(<имя-структуры>* obj);
|
||
<имя-структуры> * <префикс-функции>_destroy(<имя-структуры>* obj, bool self_destroy);
|
||
```
|
||
|
||
Функция инициализации объекта `*_init` может принимать любое количество аргументов.
|
||
Функции очистки `*_clean` `*_clean_all` могут возвращать любое значение, обычно void.
|
||
|
||
Если в функцию инициализации объекта `*_init` передать `NULL` в качестве первого аргумента (объект) то функция должна вернуть статус `MyCORE_STATUS_ERROR_OBJECT_NULL`.
|
||
|
||
Если при вызове функции `*_destroy` аргумент `self_destroy` указан как `true` то возвращаемое значение всегда должно быть равно `NULL`, иначе возвращается переданный в аргументах объект `obj`.
|
||
|
||
Данный подход был реализован для работы с динамически выделенными объектами и теми что находятся в стеке (статические).
|
||
|
||
Пример с динамически выделенным объектом:
|
||
```C
|
||
mycore_utils_array_t *array = mycore_utils_array_create();
|
||
mystatus_t status = mycore_utils_array_init(array, 1024);
|
||
if(status)
|
||
exit(EXIT_FAILURE);
|
||
|
||
mycore_utils_array_destroy(array, true);
|
||
```
|
||
|
||
Пример с объектом из стека:
|
||
```C
|
||
mycore_utils_array_t array;
|
||
mystatus_t status = mycore_utils_array_init(&array, 1024);
|
||
if(status)
|
||
exit(EXIT_FAILURE);
|
||
|
||
mycore_utils_array_destroy(&array, false);
|
||
```
|
||
|
||
Пример API инициализации для ARRAY:
|
||
```C
|
||
mycore_utils_array_t * mycore_utils_array_create(void);
|
||
mystatus_t mycore_utils_array_init(mycore_utils_array_t* array, size_t start_size);
|
||
void mycore_utils_array_clean(mycore_utils_array_t* array);
|
||
mycore_utils_array_t * mycore_utils_array_destroy(mycore_utils_array_t* array, bool self_destroy);
|
||
```
|
||
|
||
Стоит отметить, что данный подход не является абсолютным постулатом. Бывают случаи когда приходится реализовывать иное API, но всё же, в большинстве случаев именно такое. Нужно быть разумным и понимать что делаешь, а не слепо следовать правилам.
|
||
|
||
### Память
|
||
|
||
Для работы с динамической памятью используются четыре функции:
|
||
```C
|
||
void * mycore_malloc(size_t size);
|
||
void * mycore_calloc(size_t num, size_t size);
|
||
void * mycore_realloc(void* dst, size_t size);
|
||
void * mycore_free(void* dst);
|
||
```
|
||
|
||
Функции определены в `mycore/myosi.h`, реализованы в `myport/*/mycore/memory.c` и могут быть переопределены.
|
||
|
||
Из названий понятно, что это обвязки для стандартных функций `malloc, calloc , realloc, free`.
|
||
В отличии от стандартной функции `free` функция `mycore_free` возвращает значение `void *` которое всегда равно `NULL` — это своеобразный синтаксический сахар, чтобы отдельно не занулять переменные после освобождения.
|
||
|
||
К примеру,
|
||
```C
|
||
if(object->table)
|
||
object->table = mycore_free(object->table);
|
||
```
|
||
|
||
Иначе пришлось бы писать:
|
||
```C
|
||
if(object->table) {
|
||
mycore_free(object->table);
|
||
object->table = NULL:
|
||
}
|
||
```
|
||
|
||
**О работе с памятью**
|
||
|
||
Плохим тоном считается постоянное выделение и освобождение памяти. Выделенную один раз память можно использовать многократно — об этом часто забывают.
|
||
|
||
Для примера, `myhtml` строит дерево `HTML` для которого создается много нод, 500 нод в среднем на одну страницу. У каждой ноды есть параметры. Если мы будем каждый раз дёргать malloc, а в случаи освобождения всех нод free, то программа у нас будет работать медленно, очень медленно.
|
||
Для этого в проекте созданы "менеджеры памяти/объектов" которые выделяют куски памяти под структуры и следят за ними. Читайте про `dobject` и `mraw`.
|
||
|
||
### Исходные файлы и глобальные переменные
|
||
|
||
В проекте заведено так, что каждый файл `*.h` и `*.c` отвечает за свою область.
|
||
|
||
**Плохо** когда исходный файл содержит в себе функции для работы с несколькими структурами/объектами по смыслу никак не схожие между собой.
|
||
|
||
**Файлы с данными**
|
||
|
||
Не желательно вставлять данные (глобальные переменные, "ресурсы") в один файл с описанием функций, структур. Так же не желательно вставлять ресурсы в исходный код `*.c`. Всё это может вызвать проблемы.
|
||
Для ресурсов создается отдельный файл заголовков `*.h` в котором находятся только нужные ресурсы. И включается данный файл только в исходник `*.c`.
|
||
|
||
Например:
|
||
|
||
```C
|
||
/* файл /source/mycore/utils/resources.h */
|
||
|
||
#ifndef MyCORE_UTILS_RESOURCES_H
|
||
#define MyCORE_UTILS_RESOURCES_H
|
||
|
||
static const unsigned char mycore_string_hex_to_char_map[] = {
|
||
0x30, 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37, 0x38,
|
||
0x39, 0x41, 0x42, 0x43, 0x44, 0x45, 0x46, 0x00
|
||
};
|
||
|
||
#endif /* MyCORE_UTILS_RESOURCES_H */
|
||
```
|
||
|
||
```C
|
||
/* файл /source/mycore/mystring.c */
|
||
|
||
#include "mycore/utils/resources.h"
|
||
|
||
void mycore_string_some(void)
|
||
{
|
||
printf("%c\n", mycore_string_hex_to_char_map[0]);
|
||
}
|
||
```
|
||
|
||
|
||
### Заголовочные файлы
|
||
|
||
Все пути указываются относительно `/source/` директории. Для примера, если нам нужно подключить заголовок от модуля `myurl` который находится в каталоге `/source/myurl/`: `#include "myurl/url.h"`
|
||
|
||
При подключении любых внутренних модулей используются кавычки (U+0022 QUOTATION MARK (")).
|
||
|
||
### Шаблон для всех *.h и *.c файлов
|
||
|
||
**\*.h**
|
||
|
||
```C
|
||
/*
|
||
Copyright (C) 2017 Alexander Borisov
|
||
|
||
This library is free software; you can redistribute it and/or
|
||
modify it under the terms of the GNU Lesser General Public
|
||
License as published by the Free Software Foundation; either
|
||
version 2.1 of the License, or (at your option) any later version.
|
||
|
||
This library is distributed in the hope that it will be useful,
|
||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
||
Lesser General Public License for more details.
|
||
|
||
You should have received a copy of the GNU Lesser General Public
|
||
License along with this library; if not, write to the Free Software
|
||
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
|
||
|
||
Author: <почта>@<автора>.com (Имя Фамилия)
|
||
*/
|
||
|
||
#ifndef <ПУТЬ-К-ФАЙЛУ>_<НАЗВАНИЕ-ФАЙЛА>_H
|
||
#define <ПУТЬ-К-ФАЙЛУ>_<НАЗВАНИЕ-ФАЙЛА>_H
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif
|
||
|
||
/* some code */
|
||
|
||
#ifdef __cplusplus
|
||
} /* extern "C" */
|
||
#endif
|
||
|
||
#endif <ПУТЬ-К-ФАЙЛУ>_<НАЗВАНИЕ-ФАЙЛА>_H
|
||
```
|
||
|
||
**\*.c**
|
||
|
||
```C
|
||
/*
|
||
Copyright (C) 2017 Alexander Borisov
|
||
|
||
This library is free software; you can redistribute it and/or
|
||
modify it under the terms of the GNU Lesser General Public
|
||
License as published by the Free Software Foundation; either
|
||
version 2.1 of the License, or (at your option) any later version.
|
||
|
||
This library is distributed in the hope that it will be useful,
|
||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
||
Lesser General Public License for more details.
|
||
|
||
You should have received a copy of the GNU Lesser General Public
|
||
License along with this library; if not, write to the Free Software
|
||
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
|
||
|
||
Author: <почта>@<автора>.com (Имя Фамилия)
|
||
*/
|
||
|
||
#include "<путь к заголовку>.h"
|
||
|
||
```
|
||
|
||
### Примеры
|
||
|
||
Для значимых участков кода создаются примеры его использования в директории `/examples/`. Это помогает осваивать код и показывает его возможности.
|
||
|
||
### Тестирование
|
||
|
||
Для всего, практически для всего, должны создаваться тесты в директории `/test/`. Проект большой, регрессия наступает очень быстро. Я как автор проекта грешил тем что не создавал с самого начала тесты, уже пару раз сильно поплатился за это.
|
||
|
||
Не нужно лениться, желательно всегда прогонять созданный/изменённый код с Runtime Sanitization: address, thread, undefined behavior и прочими инструментами по анализу кода, работы программы. К примеру, Valgrind.
|
||
|
||
### Контребьютеру
|
||
|
||
Если вы создали какой либо файл или внесли значительные изменения в существующий то добавляете себя как автора в этот файл после информаци о лицензии.
|
||
|
||
```C
|
||
/*
|
||
...
|
||
|
||
Author: <почта>@<автора>.com (Имя1 Фамилия1)
|
||
Author: <почта>@<автора>.com (Имя2 Фамилия2)
|
||
Author: <почта>@<автора>.com (Имя3 Фамилия3)
|
||
*/
|
||
```
|
||
|
||
Пожалуйста, не стоит вносить себя как автора если мы исправили грамматическую ошибку или поменяли имя функции/переменной.
|
||
|
||
Так же, внося добавления/изменения в существующий код вы соглашаетесь на то что ваш код будет распространяться под текущей лицензией проекта. Внесённые вами добавления/изменения могут быть изменены или удален из проекта в любое время, или распространяться вместе с проектом неопределенное время.
|
||
|
||
### Лицензия
|
||
|
||
Текущая лицензия проекта `LGPL2.1`
|
||
Смотрите файл LICENSE в корне проекта.
|