From 7b98eee156c3251bdd37a4d22d3596ba671a447c Mon Sep 17 00:00:00 2001 From: Naeel Date: Wed, 29 Apr 2026 20:51:44 +0400 Subject: [PATCH] cleanup: remove reasoning comments and translate helper docs --- analysis/cleanup-worklog-2026-04-29.md | 91 +++++++++++++++++++ v1/lib/TokenGenerator.cfc | 87 ++++++------------- v1/lib/field_set.cfm | 8 +- v1/lib/order_build.cfm | 4 +- v1/lib/rest_api_helper.cfc | 115 +++++-------------------- v1/resources/svc_default.cfc | 1 - 6 files changed, 145 insertions(+), 161 deletions(-) diff --git a/analysis/cleanup-worklog-2026-04-29.md b/analysis/cleanup-worklog-2026-04-29.md index c19b9ee..c749a8b 100644 --- a/analysis/cleanup-worklog-2026-04-29.md +++ b/analysis/cleanup-worklog-2026-04-29.md @@ -312,3 +312,94 @@ - сделать второй проход по прикладным файлам - удалить комментарии в формате рассуждений там, где они явно не нужны для понимания текущей логики - отдельно обработать `v1/Application.cfc` как специальный случай + +## Обновление: второй проход по комментариям-рассуждениям + +Дата фиксации: 2026-04-29 20:45:13 +0400. + +### Что сделано + +Во втором проходе очищались не version-header блоки, а именно комментарии в стиле внутренних сомнений, оценок и рассуждений автора. + +Обработаны файлы: +- `v1/lib/field_set.cfm` +- `v1/lib/order_build.cfm` +- `v1/resources/svc_default.cfc` +- `v1/lib/rest_api_helper.cfc` + +Удалялись в первую очередь такие типы комментариев: +- сомнения автора в корректности подхода +- эмоциональные оценки вроде "некрасиво" +- внутренние заметки вида "не уверен", "не нравится", "странно" +- краткие следы от отладочных/временных рассуждений + +### Что не удалялось + +- технические комментарии, поясняющие назначение параметров и смысл структуры данных +- комментарии, нужные для понимания формата вызова или ограничений API +- комментарии, которые пока относятся к будущему этапу перевода, а не удаления + +### Проверка + +После второго прохода измененные файлы проверены на ошибки. +Результат: +- синтаксических ошибок не обнаружено + +### Промежуточный вывод + +Эта стратегия работает лучше, чем агрессивная массовая чистка: можно постепенно отделять лишние авторские рассуждения от реально полезных технических пояснений. + +### Следующий шаг + +- перевести оставшиеся английские комментарии в уже обработанных небольших файлах +- отдельно обработать `v1/lib/TokenGenerator.cfc`, где комментарии почти полностью англоязычные +- затем перейти к следующей группе прикладных файлов + +## Обновление: дополнительные commented-out блоки и перевод комментариев + +Дата фиксации: 2026-04-29 20:48:58 +0400. + +### Что сделано перед переводом + +Перед этапом перевода был выполнен еще один безопасный шаг: +- удалены крупные закомментированные legacy-блоки в `v1/lib/rest_api_helper.cfc` +- удален закомментированный альтернативный блок base64url-преобразования в `v1/lib/TokenGenerator.cfc` + +Причина: +- переводить комментарии вокруг уже неиспользуемого мертвого кода не имеет смысла +- сначала убирается то, что точно не участвует в runtime + +### Что переведено на русский + +Перевод выполнен в следующих файлах: +- `v1/lib/TokenGenerator.cfc` +- `v1/lib/field.cfm` +- `v1/lib/order_build.cfm` +- `v1/lib/filter_build.cfm` +- `v1/lib/rest_api_helper.cfc` + +Переводились: +- `hint`-описания функций и компонентов +- английские технические комментарии +- внутренние пояснения о поведении генератора токенов и helper-логики + +Что сознательно не переводилось: +- runtime-сообщения ошибок и исключений +- публичные текстовые значения, которые могут участвовать в API-контракте + +### Проверка + +После удаления закомментированных блоков и после перевода комментариев проверены измененные файлы. +Результат: +- синтаксических ошибок не обнаружено + +### Промежуточный вывод + +На этом этапе уже очищен и приведен к более однородному виду значимый кусок вспомогательного слоя `v1/lib`. +Это хорошая база перед переходом к более рискованным файлам уровня `Application.cfc` и крупных `resources/*.cfc`. + +### Следующий шаг + +- посмотреть текущее diff-состояние cleanup-ветки +- зафиксировать сделанные этапы в коммитах +- затем перейти к следующей группе файлов, начиная с наиболее контролируемых resource-компонентов diff --git a/v1/lib/TokenGenerator.cfc b/v1/lib/TokenGenerator.cfc index 7f9e74a..c3c883c 100644 --- a/v1/lib/TokenGenerator.cfc +++ b/v1/lib/TokenGenerator.cfc @@ -1,19 +1,18 @@ component /*https://www.bennadel.com/blog/2976-trying-to-generate-cryptographically-strong-random-tokens-in-coldfusion.htm*/ output = false - hint = "I generate random tokens using Java's SecureRandom class." + hint = "Генерирует случайные токены с помощью Java SecureRandom." { /** - * I initialize the token generator. + * Инициализирует генератор токенов. * * @output false */ public any function init() { - // I am the generator implementation used to generate the random token data. - // -- - // NOTE: The SHA1PRNG is not the default in all implementations of the JVM. As - // such, we're defining the algorithm explicitly to keep this code consistent. + // Реализация генератора, используемая для построения случайных токенов. + // SHA1PRNG не является алгоритмом по умолчанию во всех реализациях JVM, + // поэтому он задается явно для предсказуемого поведения. generator = createObject( "java", "java.security.SecureRandom" ) .getInstance( javaCast( "string", "SHA1PRNG" ), @@ -21,22 +20,14 @@ component /*https://www.bennadel.com/blog/2976-trying-to-generate-cryptographica ) ; - // Now that we've initialized the random generator, we have to generate a random - // byte of data. This will ensure that the random generator is self-seeded using - // a shared seed generator. - // -- - // CAUTION: Since the underlying seed generator reads from sources of entropy, - // this may hang until enough entropy has been collected. This is another good - // reason to do it during initialization time rather than at first-use time. + // После инициализации нужно сгенерировать случайный байт, + // чтобы генератор сам засеялся через общий источник seed. + // Это может блокироваться до накопления достаточной энтропии, + // поэтому операция выполняется при инициализации, а не при первом использовании. generator.nextBytes( charsetDecode( " ", "utf-8" ) ); - // I hold the future date at which time the generator should be reseeded in order - // to keep it unpredictable. - // -- - // NOTE: This doesn't affect the randomness of the values. But, the thinking - // is that the longer the generator is producing values using the same seed, - // the more likely an attacker is to be able to determine the original seed by - // passively observing generated values. + // Момент следующего пересева генератора. + // Это снижает риск слишком долгой работы с одним и тем же seed. reseedAt = getNextReseedAt(); return( this ); @@ -44,34 +35,23 @@ component /*https://www.bennadel.com/blog/2976-trying-to-generate-cryptographica } - // --- - // PUBLIC METHODS. - // --- + // Публичные методы. /** - * I generate "cryptographically strong" random token strings that are based on the - * given number of random bytes. The random bytes are subsequently encoded using a - * base64url character-set so that they are URL-safe and can be used in a variety of - * contexts. And, since base65url is a case-sensitive schema, the tokens will - * naturally be case-sensitive. + * Генерирует криптографически стойкий токен из заданного числа случайных байтов. + * Байт-массив кодируется в форму, пригодную для использования в URL. * - * @byteCount I am the number of random bytes used to generate the token. + * @byteCount Количество случайных байтов для генерации токена. * @output false */ public string function nextToken( numeric byteCount = 32 ) { - // Check to see if the generator needs to be reseeded (using a double-check - // locking approach to reduce the bottleneck). + // Проверяем, нужен ли пересев генератора. if ( now() >= reseedAt ) { - // Synchronize the reseeding. - // -- - // NOTE: From what I have read, I DON'T BELIEVE that .generateSeed() will - // ever hang with the SHA1PRNG algorithm. However, it is unclear to me. As - // such, I'm using [throwOnTimeout = false] so that parallel threads won't - // error if the lock cannot be obtained in a timely manner and will just - // fall through to using the generator with the pre-seeding state. + // Пересев выполняется под lock, чтобы уменьшить гонки между потоками. + // Если lock не получен вовремя, поток продолжает работу с текущим состоянием генератора. lock name = "TokenGenerator.reseedCheck" type = "exclusive" @@ -79,27 +59,21 @@ component /*https://www.bennadel.com/blog/2976-trying-to-generate-cryptographica throwOnTimeout = false { - // Perform double-check - generator may have already been reseeded by - // a parallel request. + // Повторная проверка внутри lock: другой поток мог уже обновить seed. if ( now() >= reseedAt ) { reseedAt = getNextReseedAt(); - // NOTE: Once the generator was seeded internally, this re-seeding - // will only ever "add to" the existing seed. As such, this is still - // building on top of the original randomness and calling this, on - // interval, this will never reduce randomness. + // Новый seed добавляется к уже существующему внутреннему состоянию генератора. generator.setSeed( generator.generateSeed( javaCast( "int", 32 ) ) ); } - } // END: Lock. + } } - // Create the byte buffer into which the random bytes will be written. Since - // there's no "correct" way to generate a byte array in ColdFusion, we can - // generate a string of the desired length and then decode it into bytes. + // Создаем буфер байтов, в который будут записаны случайные значения. var byteBuffer = charsetDecode( repeatString( " ", byteCount ), "utf-8" ); generator.nextBytes( byteBuffer ); @@ -109,27 +83,18 @@ component /*https://www.bennadel.com/blog/2976-trying-to-generate-cryptographica } - // --- - // PRIVATE METHODS. - // --- + // Приватные методы. /** - * I encode the given byte array using the base64url character-set. + * Кодирует массив байтов в строку токена. * - * @bytes I am the byte array being encoded. + * @bytes Кодируемый массив байтов. * @output false */ private string function encodeBytes( required binary bytes ) { var token = binaryEncode( bytes, "base64" ); // *** вот поэтому длина отличается от заявленной - - // Replace the characters that are not allowed in the base64url format. The - // characters [+, /, =] are removed for URL-based base64 values because they - // have significant meaning in the context of URL paths and query-strings. - /*token = replace( token, "+", "-", "all" ); - token = replace( token, "/", "_", "all" ); - token = replace( token, "=", "", "all" ); */ // мы хотим убрать все спецсимволы, потому что мы используем токен в качестве псевдослучайного суффикса token = replace( token, "+", "a", "all" ); @@ -142,7 +107,7 @@ component /*https://www.bennadel.com/blog/2976-trying-to-generate-cryptographica /** - * I calculate the next date of reseeding. + * Вычисляет время следующего пересева генератора. * * @output false */ diff --git a/v1/lib/field_set.cfm b/v1/lib/field_set.cfm index a678dc0..5c3f1d8 100644 --- a/v1/lib/field_set.cfm +++ b/v1/lib/field_set.cfm @@ -1,7 +1,7 @@  - + - + @@ -19,11 +19,9 @@ - - @@ -52,7 +50,7 @@ - + diff --git a/v1/lib/order_build.cfm b/v1/lib/order_build.cfm index 7d95daa..3bd8348 100644 --- a/v1/lib/order_build.cfm +++ b/v1/lib/order_build.cfm @@ -1,5 +1,5 @@ - + @@ -9,7 +9,7 @@ - + diff --git a/v1/lib/rest_api_helper.cfc b/v1/lib/rest_api_helper.cfc index d9f2446..440688d 100644 --- a/v1/lib/rest_api_helper.cfc +++ b/v1/lib/rest_api_helper.cfc @@ -1,18 +1,17 @@ + hint="Статические вспомогательные методы для ReST API"> + hint="Заменяет пустое поле на null"> - - + @@ -23,7 +22,7 @@ + hint="Возвращает аргумент без изменений"> @@ -33,7 +32,7 @@ access="public" returntype="any" output="false" - hint="put data into struct, replace empty fields with null"> + hint="Записывает данные в структуру, заменяя пустые поля на null"> @@ -65,9 +64,7 @@ - - @@ -78,13 +75,10 @@ + hint="Разбирает и собирает параметры фильтра из URL. Операторы задаются в filter_build"> - - - - + @@ -93,7 +87,7 @@ - + @@ -134,12 +128,10 @@ - - + hint="Разбирает и собирает параметры фильтра; операторы задаются в filter_build"> - + @@ -147,7 +139,7 @@ - + @@ -189,7 +181,7 @@ + hint="Разбирает и собирает параметр сортировки"> @@ -203,7 +195,7 @@ - + @@ -223,7 +215,7 @@ + hint="Разбирает и собирает параметр сортировки в числовой нотации"> @@ -237,7 +229,7 @@ - + @@ -252,35 +244,9 @@ - - - - - + + hint="Преобразует query в массив структур. Имена ключей приводятся к нижнему регистру, пустые поля считаются null"> @@ -308,7 +274,7 @@ access="public" returntype="any" output="false" - hint="convert snake style name to camel style name"> + hint="Преобразует имя в стиле snake_case в camelCase"> @@ -318,7 +284,7 @@ access="public" returntype="any" output="false" - hint="convert camel style name to snake style name"> + hint="Преобразует имя в стиле camelCase в snake_case"> @@ -327,7 +293,7 @@ access="public" returntype="any" output="true" - hint="formats Exception for display"> + hint="Форматирует сообщение для вывода"> @@ -342,7 +308,7 @@ access="public" returntype="any" output="true" - hint="formats Exception for display"> + hint="Форматирует исключение для вывода"> @@ -357,7 +323,7 @@ access="public" returntype="any" output="true" - hint="formats Bad Request Exception"> + hint="Форматирует ошибку Bad Request"> @@ -366,41 +332,6 @@ - - + hint="Проверяет поле структуры, если оно существует"> diff --git a/v1/resources/svc_default.cfc b/v1/resources/svc_default.cfc index 1845324..02af28e 100644 --- a/v1/resources/svc_default.cfc +++ b/v1/resources/svc_default.cfc @@ -30,7 +30,6 @@ -