php исходный код комментарии
Генерируемый исходный код при помощи php
При создании проектов очень часто возникает необходимость хранить какие-либо предопределённые данные в исходном коде. Например, это могут быть изображение, выводящиеся на экран в виде значков, или строки текста, представленные в той кодировке, которую понимает дисплей.
В принципе это может быть даже массив, но отсортированный определённым образом, или используемый как хэш-таблица, где ключи нужно тщательно вычислять.
И каждый раз внесение изменений в подобные данные представляет из себя мороку.
Чтобы облегчить эту задачу, программисты пишут отдельные приложения или скрипты, которые сформируют сложный исходный код на основе простых, легко обновляемых данных.
Atmel Studio позволяет обрабатывать предсборочные события, вызывая указанные приложения каждый раз перед сборкой проекта. Задаются они на вкладке Build-Events в свойствах проекта.
Про использование этого механизма для авто-увеличения номера версии я уже писал вон там, но тогда это было отдельное приложение.
Такой подход далеко не всегда удобен, так как сам способ формирования исходников также иногда может быть необходимо изменить. И тогда придётся открывать другую IDE, открывать проект с кучей файлов, менять, компилирововать. Да и с кроссплатформенностью проблема: скомпилированный для Windows конвертор не запустится на linux, а при передаче исходников проекта кому-то придётся также передавать исходники конвертора.
PHP
Всех этих проблем помогает избежать какой-нибудь скриптовый интерпретатор. Тогда исходный файл конвертора будет один, его можно хранить вместе с проектом и он сможет работать на других платформах.
На роль такого интерпретатора подходит php
Многие знают php, как серверный скриптовый язык, где php работает совместно с http-сервером (например Apache). Но, меж тем, интерпретатор можно использовать для запуска отдельных скриптов.
Установка php
1) Идём на php.net/downloads.php и качаем последнюю версию под свою платформу. У меня используется 5я версия, сейчас уже вышла 7я — вроде бы и в ней всё работает как надо. Достаточно скачать zip-архив.
2) Разархивируем zip в любую директорию. У меня, например, php живёт в D:\Tools\php
3) Меняем переменную PATH (Жмакаем Win+Break, «Дополнительные параметры системы», вкладка «Дополнительно», кнопка «Переменные среды…» в нижнем поле «Системные переменные» ищем Path и в конец через точку-с-запятой дописываем наш путь).
После изменения PATH, Atmel Studio нужно перезагрузить, а то она не подхватит изменения.
4) В папке с php файл php.ini-development копируем в php.ini, ищём в нём блок [Date], раскомментариваем строчку «date.timezone = « и прописываем свою таймзону из этого списка. Например Europe/Moscow
В таком же виде их можно пихать в Pre-build events в проект в Atmel Studio.
Занимательный момент: Atmel Studio анализирует тектовый вывод запущенных в Pre-build events приложений. Если очередная выводимая строка начинается с «Warning:«, то текст строки будет отображен среди прочих предупреждений при сборки. А вот если строка начинается с «Error:«, то студия прервёт сборку проекта. Таким образом, использовать скрипты можно также и для проверки исходных данных.
Пример проекта
Для демонстрации я накидал небольшой проектик и разместил его на github. github.com/AterLux/prebuildevent_demo/
Этот проект просто выводит картинки на монохрномный OLED дисплей.
Скрипт конвертирует цветные 24-битные картинки размером 128×64 в монохромные и генерирует исходный код с массивами данных.
Проект написан для микроконтроллера ATMega328P и настроен для вывода на OLED-дисплей с контроллером SSD1306, поключенный по шине SPI:
— линия SCLK дисплея к выводу SCK (PB5) контроллера;
— линия SDAT дисплея к выводу MOSI (PB3) контроллера;
— линия CS# дисплея к выводу SS (PB2) контроллера;
— линия D/C# дисплея к выводу PB1 контроллера.
При использовании модулей дисплея, подключенных по SPI, контроллер должен работать от напряжения 3,3 вольта! Т.к. контроллер питается от этого напряжения и его входы не толерантны к 5В. Иначе контроллер может попортиться
В проекте запускаются 2 php скрипта перед сборкой.
В демонстрационном проекте он используется так:
Этот скрипт как раз и генерирует массивы с монохромными изображениями.
Результат его работы выглядит примерно так
В проекте он используется вот так:
Теперь, чтобы добавить новые картинки, достаточно подложить их в ту директорию, а изменить существующие можно в обычном графическом редакторе. После этого достаточно лишь пересобрать проект и они автоматически сконвертируются.
Заголовок вверху выведет ‘Это пример’.
User Contributed Notes 11 notes
Notes can come in all sorts of shapes and sizes. They vary, and their uses are completely up to the person writing the code. However, I try to keep things consistent in my code that way it’s easy for the next person to read. So something like this might help.
/* Title Here Notice the First Letters are Capitalized */
# Option 1
# Option 2
# Option 3
/*
* This is a detailed explanation
* of something that should require
* several paragraphs of information.
*/
// This is a single line quote.
?>
It is worth mentioning that, HTML comments have no meaning in PHP parser. So,
WILL execute some_function() and echo result inside HTML comment.
Comments in PHP can be used for several purposes, a very interesting one being that you can generate API documentation directly from them by using PHPDocumentor (http://www.phpdoc.org/).
Therefor one has to use a JavaDoc-like comment syntax (conforms to the DocBook DTD), example:
/**
* The second * here opens the DocBook commentblock, which could later on
* in your development cycle save you a lot of time by preventing you having to rewrite
* major documentation parts to generate some usable form of documentation.
*/
?>
Some basic html-like formatting is supported with this (ie
tags) to create something of a layout.
Actually, both are correct. Once a comment is opened, *everything* is ignored until the end of the comment (or the end of the php block) is reached.
Thus, if a comment is opened with:
// then /* and */ are «overridden» until after end-of-line
/* then // is «overridden» until after */
Be careful when commenting out regular expressions.
E.g. the following causes a parser error.
I do prefer using # as regexp delimiter anyway so it won’t hurt me 😉
In php there are 3 types of comments
1.single line c++ style comment(//)
2.single line Unix shell stype comment(#)
3.multi line c style comment(/*/)
single or multi line comment comes to the end of the line or come first to the current block of php code.
HTML code will be printed after //. > or #. >
closing tag breaks the php mode and return to html mode.
The header above will break php mode and return html mode and show ‘Standard tag:single line c++ style comment’
The header above will break php mode and return html mode and show ‘Standard tag:single line unix shell style comment’
The header above will break php mode and return html mode and show ‘Standard tag:multi line c style comment’
The header above will break php mode show a unexpected syntex error’
The header above will break php mode show a unexpected syntex error’
The header above will break php mode show a unexpected syntex error’
Short tag: single line c++ style comment
The header above will break php mode and return html mode and show ‘Short tag:single line c++ style comment’
Short tag: single line unix shell style comment
The header above will break php mode and return html mode and show ‘Short tag:single line unix shell style comment’
Short tag: multi line c style comment
The header above will break php mode and return html mode and show ‘Short tag:multi line c style comment’
Script tag: single line c++ style comment
The header above will break php mode and return html mode and show ‘Script tag:single line c++ style comment’
Script tag: multi line c style comment
The header above will break php mode and return html mode and show ‘Script tag:multi line c style comment’
Script tag: single line unix shell style comment
The header above will not break php mode
Comments do NOT take up processing power.
So, for all the people who argue that comments are undesired because they take up processing power now have no reason to comment 😉
// Control
echo microtime (), «
» ; // 0.25163600 1292450508
echo microtime (), «
» ; // 0.25186000 1292450508
?>
They take up about the same amount of time (about meaning on a repeated testing, sometimes the difference between the control and the test was negative and sometimes positive).
a trick I have used in all languages to temporarily block out large sections (usually for test/debug/new-feature purposes), is to set (or define) a var at the top, and use that to conditionally comment the blocks; an added benefit over if(0) (samuli’s comment from nov’05) is that u can have several versions or tests running at once, and u dont require cleanup later if u want to keep the blocks in: just reset the var.
personally, I use this more to conditionally include code for new feature testing, than to block it out. but hey, to each their own 🙂
this is also the only safe way I know of to easily nest comments in any language, and great for multi-file use, if the conditional variables are placed in an include 🙂
for example, placed at top of file:
and then deeper inside the file:
Изучаем комментарии в PHP
Комментарии в PHP при выполнении скрипта игнорируются препроцессором, и нужны только для людей. Разработчики часто пренебрегают комментированием кода.
Среди программистов бытует мнение, что они вспомнят, как работает код, и через шесть месяцев и через год. Еще одна причина не оставлять комментарии — уверенность в том, что код настолько хорошо написан, что он ясен и без пояснений. Но нужно помнить, что может потребоваться продолжать поддерживать созданные скрипты PHP долгое время после написания.
Не менее важная причина комментирования кода — убедиться, что последователи поддерживают или добавляют функциональность вашему творению. Они также получат пользу от чтения оставленных комментариев.
Однострочные комментарии в PHP
Перед комментариями, которые находятся на одной строке, в PHP ставятся два символа косой черты ( // ).
Следующий пример содержит однострочный PHP комментарий в коде:
Однострочный комментарий может находиться на отдельной строке, или добавляется в конец строки кода:
Однострочные комментарии также применяются, чтобы временно убрать строки кода из потока выполнения. Например, следующее изменение предыдущего примера приведет к тому, что PHP проигнорирует всю команду echo во время выполнения:
Многострочные комментарии в PHP
Многострочные комментарии для сайта PHP обернуты разделителями / * и * /. Знак /* обозначает начало блока комментариев, а */ указывает на его конец. Следующий пример демонстрирует использование многострочного комментирования:
Многострочные комментарии полезны, когда заметки, которые вы хотите вставить в код, занимают более одной строки. Возможность помечать блоки строк как комментарии позволяет избежать использования однострочного комментария в начале каждой строки.
Итоги
Пожалуйста, оставьте ваши мнения по текущей теме статьи. Мы очень благодарим вас за ваши комментарии, отклики, лайки, дизлайки, подписки!
Лучшие комменты в исходном коде
Привет, хабровчане. Я здесь писал еще не очень много, но успел попробовать несколько форматов статей. Здесь были интервью с некоторыми IT специалистами из компании в которой я работаю, переводы, гайды… Что-то зашло, что-то нет. И вот, сегодня я решил попробовать новый для себя формат.
В свободное время я иногда люблю посидеть на Quora — отвечаю на вопросы других участников, или просто читаю ответы на интересные вопросы. На днях мне попался один, довольно популярный вопрос. У треда больше тысячи подписчиков и 100+ ответов. А вопрос такой: какой лучший комментарий вам встречался в исходном коде? (Ориг. What is the best comment in source code that you have ever encountered?)
Знаю, что такие треды есть и на stackoverflow, и на reddit, но т.к. я вдохновился ответами из Quora, решил сделать подборку именно оттуда. Просмотрел большую часть ответов и выбрал парочку, которые зашли больше всего.
Ответ пользователя Costya Perepelitsa
Лучший комментарий, который я когда-либо видел, наверное, Safety Pig (Свинья Безопасности):
Я никогда не был полностью уверен, как именно она должна была помочь мне в обработке кода, но что бы там ни было, это работало.
В итоге, мы включили Safety Pig в часть нашего процесса отладки и повышения безопасности:
«То, как этот код структурирован, особенно затрудняет обнаружение утечек памяти. Добавьте Safety Pig и проводите свои изменения через Valgrind перед каждым коммитом».
«Здесь компилятор не может обеспечить безопасность типов, поэтому мы добавили Safety Pig на всякий случай».
«У меня пока нет юнит-тестов, но я добавил в них свинью». (почти сработало)
Для тех из вас, кто хотел бы иметь собственную Safety Pig — игнорируйте первую строку. Блоки кода Quora автоматически удаляют начальные пробелы в первой строке.
Ответ пользователя Sasha Krassovsky
Однажды я просматривал исходный код каких-то рандомных студенческих игр, которые я нашел на DigiPen, когда вдруг увидел это:
Естественно, я должен был посмотреть, что произойдет, если я удалю комментарий. Я удалил его и попытался перекомпилировать. Не сработало. Когда я вернул комментарий, он скомпилировался как по волшебству.
Там была ошибка LNK1000: «неизвестная ошибка; обратитесь к документации для вариантов технической поддержки». Почему этот комментарий был необходим, навсегда останется загадкой.
Ответ пользователя Rishi Kumar
Лучшее, что мне приходилось видеть, попалось в сложной программе:
И потом, примерно через пять строк это:
Ответ пользователя Chen Xu
Однажды я увидел это:
Статуя Будды благословляет твой код быть свободным от багов. Смеялся над этим какое-то время.
Из ответа пользователя Somnath Mishra
Когда-то давно я видел похожий тред на Stackoverflow и там поделился некоторыми самыми забавными комментариями, с которыми я сталкивался. Да я и сам писал много забавных комментариев, но не буду делиться ими здесь по понятным причинам.
Этот комментарий не просто веселый, а гениальный. Некоторые люди отказываются от своих литературных мечтаний, работая программистами:
(пер. Заменяет пробелами скобки в тех местах, где они вызывают стаз)
На английском звучит впечатляюще — две строчки комментария, а в них 6 рифмующихся слов.
Немного черного юмора:
Код может сделать человека атеистом:
При очистке старого кода программисты часто сталкиваются с частями, которые не используются, но не удаляют его, опасаясь возможных последствий:
(пер. Я не отвечаю за этот код. Они заставили меня писать его против моей воли)
Чистый код на PHP
Это принципы разработки ПО, взятые из книги Clean Code Роберта Мартина и адаптированные для PHP. Это руководство не по стилям программирования, а по созданию читабельного, многократно используемого и пригодного для рефакторинга кода на PHP.
Не каждый из этих принципов должен строго соблюдаться, и ещё с меньшим количеством все будут согласны. Это лишь рекомендации, не более, но все они кодифицированы в многолетнем коллективном опыте автора Clean Code.
Содержание
Переменные
Используйте значимые и произносимые имена переменных
Плохо:
Хорошо:
Для одного типа переменных используйте единый словарь
Плохо:
Хорошо:
Используйте имена, по которым удобно искать
Мы прочитаем больше кода, чем когда-либо напишем. Поэтому важно писать такой код, который будет читабелен и удобен для поиска. Но давая переменным имена, бесполезные для понимания нашей программы, мы мешаем будущим читателям. Используйте такие имена, по которым удобно искать.
Плохо:
Хорошо:
Используйте пояснительные переменные
Плохо:
Неплохо:
Так лучше, но мы всё ещё сильно зависим от регулярного выражения.
Хорошо:
С помощью именования подпаттернов снижаем зависимость от регулярного выражения.
Избегайте ментального сопоставления
Не заставляйте тех, кто будет читать ваш код, переводить значения переменных. Лучше писать явно, чем неявно.
Плохо:
Хорошо:
Не добавляйте ненужный контекст
Если имя вашего класса/объекта с чем-то у вас ассоциируется, не проецируйте эту ассоциацию на имя переменной.
Плохо:
Хорошо:
Вместо сокращённых или условных используйте аргументы по умолчанию
Плохо:
Хорошо:
Функции
Аргументы функций (в идеале два или меньше)
Крайне важно ограничивать количество параметров функций, потому что это упрощает тестирование. Больше трёх аргументов ведёт к «комбинаторному взрыву», когда вам нужно протестировать кучу разных случаев применительно к каждому аргументу.
Идеальный вариант — вообще без аргументов. Один-два тоже нормально, но трёх нужно избегать. Если их получается больше, то нужно объединять, чтобы уменьшить количество. Обычно если у вас больше двух аргументов, то функция делает слишком много. В тех случаях, когда это не так, чаще всего в качестве аргумента достаточно использовать более высокоуровневый объект.
Плохо:
Хорошо:
Функции должны делать что-то одно
Это, безусловно, самое важное правило в разработке ПО. Когда функции делают больше одной вещи, их труднее составлять, тестировать и обосновывать. А если вы можете наделить функции только какими-то одиночными действиями, то их будет легче рефакторить, а ваш код станет гораздо чище. Даже если вы не будете следовать никакой другой рекомендации, кроме этой, то всё равно опередите многих других разработчиков.
Плохо:
Хорошо:
Имена функций должны быть говорящими
Плохо:
Хорошо:
Функции должны быть лишь одним уровнем абстракции
Если у вас несколько уровней абстракции, то на функцию возложено слишком много задач. Разбиение функций позволяет многократно использовать код и облегчает тестирование.
Плохо:
Хорошо:
Уберите дублирующий код
Старайтесь полностью избавиться от дублирующего кода. Он плох тем, что если вам нужно менять логику, то это придётся делать в нескольких местах.
Представьте, что вы владеете ресторанчиком и отслеживаете, есть ли продукты: помидоры, лук, чеснок, специи и т. д. Если у вас несколько списков с содержимым холодильников, то вам придётся обновлять их все, когда вы готовите какое-то блюдо. А если список один, то и вносить изменения придётся только в него.
Зачастую дублирующий код возникает потому, что вы делаете две и более вещи, у которых много общего. Но небольшая разница между ними заставляет вас писать несколько функций, и те по большей части делают одно и то же. Удаление дублирующего кода означает, что вы создаёте абстракцию, которая может обрабатывать все различия с помощью единственной функции/модуля/класса.
Правильный выбор абстракции критически важен, поэтому нужно следовать принципам SOLID, описанным в разделе «Классы». Плохие абстракции могут оказаться хуже дублирующего кода, так что будьте осторожны! Но если можете написать хорошие, то делайте это! Не повторяйтесь, иначе окажется, что при каждом изменении вам нужно обновлять код в нескольких местах.
Плохо:
Хорошо:
Не используйте флаги в качестве параметров функций
Флаги говорят вашим пользователям, что функции делают больше одной вещи. А они должны делать что-то одно. Разделяйте свои функции, если они идут по разным ветвям кода в соответствии с булевой логикой.
Плохо:
Хорошо:
Избегайте побочных эффектов
Функция может привносить побочные эффекты, если она не только получает значение и возвращает другое значение/значения, но и делает что-то ещё. Побочным эффектом может быть запись в файл, изменение глобальной переменной или случайная отправка всех ваших денег незнакомому человеку.
Но иногда побочные эффекты бывают нужны. Например, та же запись в файл. Лучше делать это централизованно. Не выбирайте несколько функций и классов, которые пишут в какой-то один файл, используйте для этого единый сервис. Единственный.
Главная задача — избежать распространённых ошибок вроде общего состояния для нескольких объектов без какой-либо структуры; использования изменяемых типов данных, которые могут быть чем-то перезаписаны; отсутствия централизованной обработки побочных эффектов. Если вы сможете это сделать, то будете счастливее подавляющего большинства других программистов.
Плохо:
Хорошо: