README

"Broken OOP" 是一组注释，用于帮助描述在代码阅读或代码审查过程中遇到的常见面向对象编程（OOP）问题。每个注释都简洁地解释了一个面向对象设计缺陷。它包含了一些小示例来帮助理解，以及指向已经思考过该问题的杰出作者的参考文献。

动机

通常，当我审查代码时，看到许多可以修复或改进的设计缺陷或错误，我会遇到两个问题：

1. 清晰地解释为什么可以改进可能是复杂或耗时的。这很遗憾，因为许多优秀的大脑已经写了很多关于这个特定缺陷的文章。

2. 有时，我没有时间立即重构，但仍然不希望失去改进这段代码的事实。有时，由于对项目了解不足，我不知道这种变化的所有后果，只想向主要开发者强调问题。

因此，"Broken OOP" 是一个 教育工具，旨在在面向对象编程的常见设计问题方面建立共识。

灵感来源

拥有一个教育工具很好，但如果开发人员不能无缝地使用它，那么它就没有什么用。知识的主要来源（技术和功能）应该是代码。感谢 Cyrille Martraire 的书 Living Documentation，他在书中描述了注释如何强大且简单，对开发者来说非常有用。

PHP 注释不是现成的，现有的实现方式与 Java 等其他语言相比确实相去甚远；但仍然是一个用于此类项目的良好简单工具。

入门

安装

请勿在生产环境中使用此工具，而应仅用于开发。

composer require --dev "jjanvier/broken-oop"

如何使用？

由于该项目使用 Doctrine annotations，它兼容许多 IDE 或文本编辑器。通常，它通过 Symfony2 插件与 PHPStorm 或 Eclipse 一起使用。有关更多信息，请参阅Doctrine annotations 的文档。

这意味着，通过在您喜欢的 IDE 中使用 CTRL+click，您应该能够查看注释，并更好地理解您的同伴发现的问题。

todo gif with phpstorm

贡献

以下是要添加新注释时需要遵循的规则列表

• 每个注释都应该指出一个常见的面向对象设计缺陷。
• 每个注释都应该以它所强调的问题的通用原则命名。它不应以解决方案命名。
• 每个注释都必须包含一个描述。描述应保持简单，其作用只是介绍问题，而不是取代优秀的博客文章或书籍。
• 每个注释都必须包含几个优秀的英文非免费参考文献。
• 每个注释可以包含几个优秀的非英文免费参考文献。
• 每个注释都必须包含 examples 目录中的示例。
• 目录必须以注释的名称命名。
  • 文件 broken.php 描述了问题。问题位于 examples/broken.php
  • 每个注释都应该附有一个测试文件 test.php
  • 一个名为 enhanced.php 的文件描述了修复部分或完全解决这个问题的一种方法，但仅限此问题。请注意，该文件故意不命名为 fixed.php。有时，我们会提出更好的方案，但仍然不是最佳方案。有时，我们会解决一个问题的一部分，但另一个问题仍然存在。
  • 这些文件必须是简单的面向对象（OOP）示例。
  • 这两个文件之间的差异必须尽可能小。

如有需要，可以利用 Doctrine 的注解 的灵活性来使用目标和属性类型。

以下是新注解的模板

<?php

namespace Jjanvier\BrokenOop;

/**
 * Here goes a simple description of this common OOP design flaw.
 *
 * References:
 *  - First English free reference {@see ...}
 *  - Second English free reference {@see ...}
 *  - First English non free reference {@see ...}
 *  - [French] First French free reference {@see ...}
 *
 * @Annotation
 *
 * @author  Foo Bar
 * @license GNU GPLv3 https://open-source.org.cn/licenses/GPL-3.0
 */
class CommonOOPDesignFlaw
{

}

许可证

GNU 通用公共许可证版本 3