понедельник, 21 октября 2013 г.

Как писать комментарии

Опять я почитала книгу С. Мартина "Чистый код. Создание, анализ, рефакторинг". Ниже привожу понравившиеся советы из книги по поводу написания комментариев.

1. Программисты не могут нормально совпровождать комментарии. Программный код изменяется и эволюционирует. Его фрамгенты перемещаются из одного места в другое, размножаются и сливаются. Слишком часто комментарии отделяются от описываемого ими кода и превращаются в пометки непонятной принадлежности с постоянно снижающейся точностью. Неточные комментарии гораздо вреднее, чем отсутствие комментариев. Они обманывают и сбивают с толку программиста, создают у него невыполненные ожидания.

2. Ясный и выразительный код с минимумом комментариев гораздо лучше громоздкого сложного кода с большим количеством комментариев. Не тратьте время на написание комментариев, объясняющих созданную вами путаницу. Лучше потратьте его на исправление кода. Например, с каким кодом вы бы предпочли работать:

Зачастую задача сводится к созданию функции, чье название сообщает  то же самое, что и комментарий, который вы собирались написать.

3. Юридические комментарии - например, заявление об авторских правах. Такие комментарии не должны представлять собой трактаты. Вместо того, чтобы перечислять в комментарии все условия, по возможности ограничьтесь ссылкой на стандартную лицензию или другой внешний документ.

4. Предупреждения о последствиях - это весьма полезные комментарии. Например:


5. Иногда бывает полезно оставить заметки на будущее в форме комментариев TODO. Регулярно просматривайте такие комментарии и удаляйте те, которые потеряли актуальность.

6. Комментарий может подчеркивать важность обстоятельства, которое на первый взгляд кажется несущественным:


7. Избыточные комментарии. Читаются не проще, чем сам код. Например:

А вот еще избыточные комментарии:
8.  Использовать штуки типа Javadoc - это хорошо. Но правила, говорящие, что каждая функция должна иметь комментарий Javadoc или что каждая переменная должна быть помечена комментарием - обычная глупость. Такие комментарии только загромождают код, распространяют недостоверную информацию и вызывают общую путаницу и дезориентацию. Например, вот тут комментарий совершенно избыточен:

При всей полезности комментариев Javadoc для API общего пользования не применяйте их в коде, не предназначенном для общего потребления. 

9. Позиционные маркеры. Это строки типа:

//Действия///////////////

В отдельных случаях объединение функций под такими заголовками имеет смысл. Но в общем случае они составляют балласт, от которого следует избавиться - особенно от назойливой серии косых черт в конце. Взгляните на дело под таким углом: заголовки привлекают внимание только в том случае, если они встречаются не слишком часто.

10. В программировании редко встречаются привычки более отвратительные, чем закрытие комментариями неиспользуемого кода. Никогда не делайте этого! У других программистов, видящих закомментированный код, не хватает храбрости удалить его. Они полагают, что код оставлен не зря и слишком важен для удаления. В итоге закомментированный код скапливается, словно осадок на дне бутылки плохого вина. Системы контроля исходного кода запоминают изменения в коде за нас.

11. Не излагайте информацию системного уровня в контексте локального комментария. Примером служит следующий комментарий. Не считая того, что он избыточен, в него также включена информация о порте по умолчанию, при том, что функция никоим образом не может управлять этим значением. И конечно, ничто не гарантирует, что комментарий будет изменен при изменении кода, в котором это значение определяется. 


12. Плохо, когда сам комментарий нуждается в объяснениях. Например, (см. ниже) - что такое байты фильтра? Они как-то связаны с +1 или *3? Один пиксел соответствует одному байту? 


пятница, 18 октября 2013 г.

Монада и моноид: что это такое

Монада

Вычисления с побочными эффектами - вычисления, в ходе которых осуществляется ввод-вывод, изменение переменных. В Haskell стараются изо всех сил не работать с такими вычислениями, или хотя бы как-то их изолировать от остальных вычислений. По сути, монада - это способ организации цепочки вычислений, позволяющий добавить в программу на Haskell побочные вычисления так, чтобы они ей не повредили.

В частности, к монадам относятся:

  • IO (монада строго последовательных вычислений): стратегия связывания — «сначала первое вычисление, затем второе»;
  • Maybe (монада вычислений с отсутствующими значениями): стратегия связывания — «если первое вычисление дало результат, то второе; иначе — отсутствие результата»;
  • List (монада вычислений с несколькими результатами): стратегия связывания — «все возможные результаты второго вычисления, примененного к каждому из вычисленных первым значений параметра»;
  • State (монада вычислений с переменной состояния): стратегия связывания — «начать второе вычисление с состоянием, измененным в результате первого»;
Вот тут описан хороший пример создания и использования монады Maybe.

Моноид

Моноид - это множество с заданной на нем ассоциативной бинарной операцией и нейтральным элементом. Примерами моноидов могут служить:

  • String с операцией конкатенации и значением "пустая строка";
  • Boolean с операцией && и значением true;
  • Boolean с операцией || и значением false;
  • Integer с операцией (+) и значением 0;
  • -Integer с операцией (*) и значением 1;

и т.д.

Определения, которые помогают глубже постигнуть суть моноида

Свойство ассоциативности


Операция \(\circ\) ассоциативна, когда \(\forall x,y,z  (x\circ{y})\circ{z}=x\circ(y\circ{z})\).

Операция сложения целых чисел - ассоциативна.
Например, вычисление выражения 1 + (2 + 3) даст такой же результат, как и вычисление выражения (1 + 2) + 3  число 6.

Операция деления на множестве вещественных чисел - не ассоциативна.
Например, вычисление выражения 4/(2/2) даст число 4, а (4/2)/2 - число 1.

Бинарная операция


Бинарная операция - это математическая операция, принимающая два аргумента и и возвращающая один результат.
Примеры бинарных операций - сложение, умножение и вычитание на множестве вещественных чисел.

Нейтральный элемент

Нейтральный элемент бинарной операции - это элемент, который оставляет любой другой элемент неизменным при применении к ним этой бинарной операции. Говоря более формально, пусть \((M, \circ)\) - множество \(M\) с определенной на нем бинарной операцией \(\circ\). Элемент \(e \in M\) называется нейтральным относительно \(\circ\), если \(x\circ{e}=e\circ{x}=x\) \( \forall x \in M\).

1. Определение монады (wiki)
2. Туториал по системе переписывания термов TermWare
3. Про моноиды с примерами на F#
4. Определение ассоциативности (wiki)
5. Определение ассоциативности (ru.math.wikia)
6. Бинарная операция (wiki)
7. Определение нейтрального элемента (ru.math.wikia)


понедельник, 14 октября 2013 г.

Как сделать презентацию для конференции: клевая ссылка

Готовлю тут презентацию к конференции, а они в разделе для докладчиков выложили ссылку на такую вот замечательную памятку докладчикам:

http://wiki.4intra.net/Conference-for-speakers

http://www.powerlexis.ru/klub_powerpoint/tekstozavr/ - этот инструмент заценяет адекватность презентации, надо будет попробовать :)

А вот кстати и интутитивно понятный онлайн инструмент для построения графиков и диаграмм (полезно, когда никак навскидку не можешь вспомнить, как строить их в MS Excel):

http://www.chartgo.com/en/chartbar.jsp


суббота, 5 октября 2013 г.

Как подчистить историю коммитов (личный опыт)

В общем, мне нужно было сделать свою текущую историю коммитов на github "красивой", чтобы в ветке develop была последняя работа, а в ветке master - только стабильный, нормально работающий код. Имелась только ветка master с кучей лишних коммитов, а стабильный код был где-то пару-тройку коммитов назад.

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

Вопрос.

What I'd like to do is remove ALL the version history from the local Git repository, so the current contents of the repository appear as the only commit (and therefore older versions of files within the repository are not stored).

Ответ.

The only solution that works for me (and keeps submodules working) is
git checkout --orphan newBranch
git add -A  # Add all files and commit them
git commit
git branch -D master  # Deletes the master branch
git branch -m master  # Rename the current branch to master
Вопрос.

How to force push a reset to remote repository
(когда откатываешь master на пару коммитов назад, этот зараза отказывается пушить изменения)

Ответ.

git push origin master -f

Вопрос.

Как посмотреть, какие ветки есть и к какому коммиту прикреплена каждая ветка?

Ответ.

git show-branch --all

P.S. http://www.syntevo.com/smartgithg/documentation?page=git-flow

Информационные источники: stackoverflowеще stackoverflowдокументация Git